26 March 2012

Best Practices: comment


List of comment practices from various articles which i believe they are useful for my improvment :

NOTE! Not all points here are useful in all cases.They depends on application type and various other factors.
  1. (MOST IMPORTANT) Use comments when they  add  readability to code. 
  2. Unnecessary over-commenting in each line will reduce readability:
    int counter = 0; // assigning zero as initial value to the counter (Really?)
  3. Lack of commenting will increase time need to perform changes in code (as part of improvment,bug fixing,etc.) 
  4. Writing comments (e.g. JavaDoc declaration) for all public methods is a good practice as long as  they meet 1 point.(a)
  5. Document all "todo"s instantly when detected.These items may be remembered for that day but may not for tomorrow when not documented, so a buggy code will be inevitable. (a)
  6. Comment all method that solves particular bug. It will helps remember you a solution and helps understands somebody why you choose your algoritm to solve it.
  7. Comment all workaround method that's solve problems related to bugs/ limitiation in third party libraries /frameworks etc.
  8. Format your comments. 
  9. Comment  method that is buggy,BUT do NOT comment bugs details,use Bug tracker tools for that.
Sources:
a) http://java.dzone.com/articles/10-best-practices-code

[Update add 2 useful practices and "note!" paragraph