10 Best Practices To Follow Land Writing Code Comments

Comments are an of import business office of writing code not entirely inwards Java but whatever programming or scripting linguistic communication y'all use. At the same time, this is 1 of the most abused things every bit well. Both writing no comment together with writing also much comment is bad together with this has been highlighted past times many software gurus e.g. Robert C. Martin inwards his classic mass Clean code. There is a whole chapter dedicated to How to write comments together with finding pros together with cons of comment. This article is my learning inwards the same direction, hither I am going to percentage amongst y'all guys around 0f the dominion together with best practices I follow piece writing comments. Before that let's firstly run across what is the piece of employment of having a comment inwards the code? Why create nosotros ask comment, isn't writing code is enough. Some of the people I convey met ever fence that nosotros are getting paid for writing code together with non comment :).


Anyway inwards my persuasion nosotros all concur amongst each other that software pass entirely 10% fourth dimension of its life inwards evolution together with residual of 90% inwards maintenance. This 90% business office of maintaining the code is where comment tin aid y'all immensely. Since no unmarried developer stays till whole life of whatsoever production or software together with its oft novel people, who works of already written code. These are the people who read the code together with non aware of why a for certain slice of code has been written, hither comments tin aid them to sympathise code chop-chop together with believe me y'all volition acquire lot of roses from that swain developer :). 

Anyway long even brusk hither are around of the things I endeavor to follow piece writing code:

10 tips on writing code comments

1) Focus on readability of code; assume that y'all don't convey comments to explicate the code. Give your method, variables together with cast meaningful name.

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

//calculates foursquare origin 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 origin using Newton-Raphson method together with instead of writing comment y'all tin only rename your method together with variable every bit follows:

public void squareRoot(int num){

       origin = num/ 2;

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

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

       }

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

}

3) Always write why y'all are writing this slice of code, why y'all are writing this slice of code because this information is non visible until y'all write them inwards comments together with this is critical to position whatsoever põrnikas or deportment amongst changing delineate of piece of employment concern environment.

4) If y'all are writing gist libraries which volition move used past times unlike projection together with amongst unlike teams. Follow javadoc comment style together with document all supposition together with precondition for using your API. Joshua Bloch has also mentioned near writing Java-doc comment inwards his classic Effective Java, which is worth knowing.

5) Include JIRA Number together with description on comment, especially if y'all are modifying an existing slice of code every bit business office of maintenance. This I industrial plant life extremely useful piece comparison unlike version of code inwards CVS or SVN. This gives y'all clear thought why that particular code has been added together with whether resultant is because of that slice of code or not.


6) Always endeavor to finish your comment inwards every bit few words every bit possible, 1 liner comment is best until its explaining "Why" business office together with can't move replaced past times code itself. No trunk likes or has plenty fourth dimension to read longer comment.

7) Don't write even inwards comment every bit your name, employee id, your subdivision etc because those information tin move obtained from CVS commit information inwards representative mortal wants to know who has brand this change.

8) Always put comment piece committing code inwards source command repository together with peculiarly why y'all are adding this slice of code if possible include JIRA or QC Number hence that whatsoever 1 tin refer JIRA for consummate details.

9) If y'all desire upcoming developer to follow for certain standards or inform near for certain things together with then include them inwards the starting fourth dimension of your cast every bit comment. E.g. suppose if y'all are writing serializable cast inwards coffee together with then its expert to seat a serializable alarm stating that whatsoever novel fields add-on inwards this cast must implement serializable interface inwards java or enter transient etc.


10) Last but non the to the lowest degree hand your code to swain developer to understand every bit business office of code review together with inquire him how much he understands it.

That’s all from me on code commenting, delight percentage the standard, best practices or your sense amongst writing comments on code. I believe these are the areas which a junior developer or fifty-fifty nosotros tin amend together with it’s entirely 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

Share this post