commenting in agile development
TRANSCRIPT
Rules for documenting code
KISS
Keep it short and simple
Examples
Why do we use comments?
Why do we use comments?
Comments are failure.
Explain Yourself in Code// check if the user is administratorif (user.isRegistered && user.privileges.equals(‘admin’)) { ...}
vs.if (user.isAdmin) {...}
What is so bad aboutcomments?
What is so bad aboutcomments?
They rot.
Inaccurate comments are worse than no comments at all.
/* End slide */
Bad comments
Bad comments
...most of them.
Redundant Comments/** * The Loader implementation with which this Container is * associated. */ protected Loader loader = null;
/** * The Logger implementation with which this Container is * associated. */ protected Log logger = null;
/** * The Manager implementation with which this Container is * associated. */ protected Manager manager = null;
Redundant Comments
protected Loader loader = null; protected Log logger = null; protected Manager manager = null;
Noise Comments/** The name */private String name;
/** The version */private String version;
/** The licence */private String licence;
Scary Noise Comments/** The name */private String name;
/** The version */private String version;
/** The licence */private String licence;
/** The licence */private String info;
/** The licence */private String help;
No Comments
private String name;private String version;private String licence;private String info;private String help;
Closing Brace Comments
try { while ((line = in.readLine()) != null) { ...
} // while
} // try
Commented-out Code
public class Program{ static void Main(string[] args) { /* This block of code is no longer needed * because we found out that Y2K was a hoax * and our systems did not roll over to 1/1/1900 */ //DateTime today = DateTime.Today; //if (today == new DateTime(1900, 1, 1)) //{ // today = today.AddYears(100); // string message = "The date has been fixed for Y2K."; // Console.WriteLine(message); //} }
}
HTML Tags in Comments/** * Task to run fit tests. This task runs fitnesse tests and publishes the results. * * <pre> * Usage: * <taskdef name="execute-‐fitnesse-‐tests" classname="fitnesse.ant.ExecuteFitnesseTestsTask" classpathref="classpath" /> * OR * <taskdef classpathref="classpath" resource="tasks.properties" /> * * <execute-‐fitnesse-‐tests suitepage="FitNesse.SuiteAcceptanceTests" fitnesseport="8082" resultsdir="${results.dir}" resultshtmlpage="fit-‐results.html" classpathref="classpath" /> * </pre> */
Good comments
Informative Comments
// format matched kk:mm:ss EEE, MMM dd, yyyy
Pattern timeMatcher = Pattern.compile(
“\\d*:\\d*:\\d* \\w*, \\w* \\d*, \\d*”);
Warning of Consequences Comments
// Don’t run unless you// have some time to killpublic void _testWithReallyBigFile() { writeLinesToFile(100000000);
response.setBody(testFile); response.readyToSend(this); String responseString = output.toString(); assertSubString(“Content-‐Length: 100000000”, responseString); assertTrue(bytesSent > 100000000)}
TODO Comments
// TODO: Refactor this code
TODO Comments
// TODO: Refactor this code
// FIXME: This won't work if the file is missing.
// XXX: This method badly needs refactoring: should switch by core type.
Dynamic comments
Tests as Documentation
Unit tests = code level documentationBehaviour tests = feature documentation
Jnario.org
MessageTry to write clear self-explanatory code.
Avoid comments if possible.
Thanks
ReferencesProwareness bloghttp://www.prowareness.com/blog/anti-agile-manisfesto/
Clean Code (A Handbook of Agile Software Craftsmanship)Robert C. Martin
Jnario http://jnario.org/