Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

Commenting in Agile Development

795 views

Published on

Published in: Technology
  • Be the first to comment

  • Be the first to like this

Commenting in Agile Development

  1. 1. Rules for documenting code
  2. 2. KISS
  3. 3. Keep it short and simple
  4. 4. Examples
  5. 5. Why do we usecomments?
  6. 6. Why do we usecomments? Comments are failure.
  7. 7. Explain Yourself in Code//  check  if  the  user  is  administratorif  (user.isRegistered  &&  user.privileges.equals(‘admin’))  {  ...} vs.if  (user.isAdmin)  {...}
  8. 8. What is so bad about comments?
  9. 9. What is so bad about comments?They rot.
  10. 10. /*  End  slide  */Inaccurate comments are worse than no comments at all.
  11. 11. Badcomments
  12. 12. Badcomments ...most of them.
  13. 13. 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;
  14. 14. Redundant Comments  protected  Loader  loader  =  null;  protected  Log  logger  =  null;  protected  Manager  manager  =  null;
  15. 15. Noise Comments/**  The  name  */private  String  name;/**  The  version  */private  String  version;/**  The  licence  */private  String  licence;
  16. 16. 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;
  17. 17. No Commentsprivate  String  name;private  String  version;private  String  licence;private  String  info;private  String  help;
  18. 18. Closing Brace Commentstry  {   while  ((line  =  in.readLine())  !=  null)  {   ...     }  //  while}  //  try
  19. 19. Commented-out Codepublic  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);                //}        }}
  20. 20. 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>  */
  21. 21. Goodcomments
  22. 22. Informative Comments//  format  matched  kk:mm:ss  EEE,  MMM  dd,  yyyyPattern  timeMatcher  =  Pattern.compile( “d*:d*:d*  w*,  w*  d*,  d*”);
  23. 23. Warning of Consequences Comments //  Don’t  run  unless  you //  have  some  time  to  kill public  void  _testWithReallyBigFile()  {   writeLinesToFile(100000000);   response.setBody(testFile);   response.readyToSend(this);   String  responseString  =  output.toString();   assertSubString(“Content-­‐Length:  100000000”,                  responseString);   assertTrue(bytesSent  >  100000000) }
  24. 24. TODO Comments//  TODO:  Refactor  this  code
  25. 25. TODO Comments //  TODO:  Refactor  this  code //  FIXME:  This  wont  work  if  the  file  is   missing.  //  XXX:  This  method  badly  needs  refactoring:   should  switch  by  core  type.
  26. 26. Dynamiccomments
  27. 27. Tests as DocumentationUnit tests = code level documentationBehaviour tests = feature documentation
  28. 28. Jnario.org
  29. 29. MessageTry to write clear self-explanatory code.Avoid comments if possible.
  30. 30. Thanks
  31. 31. ReferencesProwareness bloghttp://www.prowareness.com/blog/anti-agile-manisfesto/Clean Code (A Handbook of Agile Software Craftsmanship)Robert C. MartinJnariohttp://jnario.org/

×