Commenting in Agile Development

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:  *  &lt;taskdef  name=&quot;execute-­‐fitnesse-­‐tests&quot;  classname=&quot;fitnesse.ant.ExecuteFitnesseTestsTask&quot;  classpathref=&quot;classpath&quot;  /&gt;  *  OR  *  &lt;taskdef  classpathref=&quot;classpath&quot;  resource=&quot;tasks.properties&quot;  /&gt;  *    *  &lt;execute-­‐fitnesse-­‐tests  suitepage=&quot;FitNesse.SuiteAcceptanceTests&quot;  fitnesseport=&quot;8082&quot;  resultsdir=&quot;${results.dir}&quot;  resultshtmlpage=&quot;fit-­‐results.html&quot;  classpathref=&quot;classpath&quot;  /&gt;  *  </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/