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.
- (MOST IMPORTANT) Use comments when they add readability to code.
- Unnecessary over-commenting in each line will reduce readability:
int counter = 0; // assigning zero as initial value to the counter (Really?) - Lack of commenting will increase time need to perform changes in code (as part of improvment,bug fixing,etc.)
- Writing comments (e.g. JavaDoc declaration) for all public methods is a good practice as long as they meet 1 point.(a)
- 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)
- 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.
- Comment all workaround method that's solve problems related to bugs/ limitiation in third party libraries /frameworks etc.
- Format your comments.
- Comment method that is buggy,BUT do NOT comment bugs details,use Bug tracker tools for that.
a) http://java.dzone.com/articles/10-best-practices-code
[Update add 2 useful practices and "note!" paragraph
No comments:
Post a Comment