10 Best Practices To Follow Piece Writing Code Comments

Comments are an of import business office of writing code not alone inward Java but whatever programming or scripting linguistic communication yous use. At the same time, this is i of the most abused things equally well. Both writing no comment as well as writing equally good much comment is bad as well as this has been highlighted past times many software gurus e.g. Robert C. Martin inward his classic mass Clean code. There is a whole chapter dedicated to How to write comments as well as finding pros as well as cons of comment. This article is my learning inward the same direction, hither I am going to part alongside yous guys roughly 0f the dominion as well as best practices I follow piece writing comments. Before that let's firstly encounter what is the role of having a comment inward the code? Why produce nosotros ask comment, isn't writing code is enough. Some of the people I convey met ever debate that nosotros are getting paid for writing code as well as non comment :).


Anyway inward my sentiment nosotros all handgrip alongside each other that software pass alone 10% fourth dimension of its life inward evolution as well as residuum of 90% inward maintenance. This 90% business office of maintaining the code is where comment tin assist yous immensely. Since no unmarried developer stays till whole life of whatever production or software as well as its oft novel people, who plant of already written code. These are the people who read the code as well as non aware of why a for certain slice of code has been written, hither comments tin assist them to empathize code rapidly as well as believe me yous volition acquire lot of roses from that immature human developer :). 

Anyway long storey brusk hither are roughly of the things I travail to follow piece writing code:

10 tips on writing code comments

1) Focus on readability of code; assume that yous don't convey comments to explicate the code. Give your method, variables as well as degree meaningful name.

2) Don't write what code is doing, this should last left for the code to explicate as well as tin last easily done past times giving class, variable as well as method meaningful name. For example:

//calculates foursquare beginning of given number 

//using Newton-Raphson method

public void abc(int a){

       r = a / 2;

       piece ( abs( r - (a/r) ) > t ) {

       r = 0.5 * ( r + (a/r) );

       }

       System.out.println( "r = " + r );

}

Above code is calculating foursquare beginning using Newton-Raphson method as well as instead of writing comment yous tin only rename your method as well as variable equally follows:

public void squareRoot(int num){

       beginning = num/ 2;

       piece ( abs(root - (num/ root) ) > t ) {

       r = 0.5 * (root + (num/ root));

       }

       System.out.println( " beginning = " + beginning );

}

3) Always write why yous are writing this slice of code, why yous are writing this slice of code because this information is non visible until yous write them inward comments as well as this is critical to position whatever põrnikas or behaviour alongside changing concern environment.

4) If yous are writing center libraries which volition last used past times dissimilar projection as well as alongside dissimilar teams. Follow javadoc comment style as well as document all supposition as well as precondition for using your API. Joshua Bloch has also mentioned virtually writing Java-doc comment inward his classic Effective Java, which is worth knowing.

5) Include JIRA Number as well as description on comment, especially if yous are modifying an existing slice of code equally business office of maintenance. This I institute extremely useful piece comparison dissimilar version of code inward CVS or SVN. This gives yous clear thought why that particular code has been added as well as whether consequence is because of that slice of code or not.


6) Always travail to finish your comment inward equally few words equally possible, i liner comment is best until its explaining "Why" business office as well as can't last replaced past times code itself. No trunk likes or has plenty fourth dimension to read longer comment.

7) Don't write storey inward comment equally your name, employee id, your subdivision etc because those information tin last obtained from CVS commit information inward illustration mortal wants to know who has brand this change.

8) Always put comment piece committing code inward source command repository as well as peculiarly why yous are adding this slice of code if possible include JIRA or QC Number hence that whatever i tin refer JIRA for consummate details.

9) If yous desire upcoming developer to follow for certain standards or inform virtually for certain things hence include them inward the firstly of your degree equally comment. E.g. suppose if yous are writing serializable degree inward coffee hence its skilful to pose a serializable alarm stating that whatever novel fields improver inward this degree must implement serializable interface inward java or acquire far transient etc.


10) Last but non the to the lowest degree give your code to immature human developer to understand equally business office of code review as well as enquire him how much he understands it.

That’s all from me on code commenting, delight part the standard, best practices or your sense alongside writing comments on code. I believe these are the areas which a junior developer or fifty-fifty nosotros tin ameliorate as well as it’s alone possible from learning which each mother's experience.
Happy weekend :)

Further Learning
SOLID Principles of Object Oriented Design
From 0 to 1: Design Patterns - 24 That Matter - In Java
Clean Code: Writing Code for Humans