Se ha denunciado esta presentación.
Utilizamos tu perfil de LinkedIn y tus datos de actividad para personalizar los anuncios y mostrarte publicidad más relevante. Puedes cambiar tus preferencias de publicidad en cualquier momento.
Rules for documenting code
KISS
Keep it short and simple
Examples
Why do we usecomments?
Why do we usecomments?        Comments are failure.
Explain Yourself in Code//	  check	  if	  the	  user	  is	  administratorif	  (user.isRegistered	  &&	  user.privileges.eq...
What is so bad about         comments?
What is so bad about         comments?They rot.
/*	  End	  slide	  */Inaccurate comments are worse   than no comments at all.
Badcomments
Badcomments     ...most of them.
Redundant Comments/**	  *	  The	  Loader	  implementation	  with	  which	  this	  Container	  is	  *	  associated.	  */	  ...
Redundant Comments	  protected	  Loader	  loader	  =	  null;	  protected	  Log	  logger	  =	  null;	  protected	  Manager	...
Noise Comments/**	  The	  name	  */private	  String	  name;/**	  The	  version	  */private	  String	  version;/**	  The	  ...
Scary Noise Comments  /**	  The	  name	  */  private	  String	  name;  /**	  The	  version	  */  private	  String	  versio...
No Commentsprivate	  String	  name;private	  String	  version;private	  String	  licence;private	  String	  info;private	 ...
Closing Brace Commentstry	  {	   while	  ((line	  =	  in.readLine())	  !=	  null)	  {	   ...	  	   }	  //	  while}	  //	  ...
Commented-out Codepublic	  class	  Program{	  	  	  	  static	  void	  Main(string[]	  args)	  	  	  	  {	  	  	  	  	  	 ...
HTML Tags in Comments/**	  *	  Task	  to	  run	  fit	  tests.	  This	  task	  runs	  fitnesse	  tests	  and	  publishes	  ...
Goodcomments
Informative Comments//	  format	  matched	  kk:mm:ss	  EEE,	  MMM	  dd,	  yyyyPattern	  timeMatcher	  =	  Pattern.compile(...
Warning of Consequences Comments  //	  Don’t	  run	  unless	  you  //	  have	  some	  time	  to	  kill  public	  void	  _t...
TODO Comments//	  TODO:	  Refactor	  this	  code
TODO Comments            //	  TODO:	  Refactor	  this	  code  //	  FIXME:	  This	  wont	  work	  if	  the	  file	  is	    ...
Dynamiccomments
Tests as DocumentationUnit 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 C...
Próxima SlideShare
Cargando en…5
×

Commenting in Agile Development

  • Sé el primero en comentar

  • Sé el primero en recomendar esto

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/

×