10 Best Practices To Follow Acre Writing Code Comments

Comments are an of import business office of writing code not entirely inward Java but whatever programming or scripting linguistic communication you lot use. At the same time, this is i of the most abused things every bit well. Both writing no comment together with writing besides much comment is bad together with 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 together with finding pros together with cons of comment. This article is my learning inward the same direction, hither I am going to part amongst you lot guys to a greater extent than or less 0f the dominion together with best practices I follow piece writing comments. Before that let's foremost encounter what is the piece of job of having a comment inward the code? Why produce nosotros postulate comment, isn't writing code is enough. Some of the people I convey met e'er fence that nosotros are getting paid for writing code together with non comment :).


Anyway inward my persuasion nosotros all concord amongst each other that software pass entirely 10% fourth dimension of its life inward evolution together with residual of 90% inward maintenance. This 90% business office of maintaining the code is where comment tin aid you lot immensely. Since no unmarried developer stays till whole life of whatever production or software together with its oftentimes novel people, who industrial plant of already written code. These are the people who read the code together with non aware of why a certainly slice of code has been written, hither comments tin aid them to empathise code rapidly together with believe me you lot volition acquire lot of roses from that immature human being developer :). 

Anyway long even out curt hither are to a greater extent than or less of the things I endeavour to follow piece writing code:

10 tips on writing code comments

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

2) Don't write what code is doing, this should hold out left for the code to explicate together with tin hold out easily done past times giving class, variable together with 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 together with instead of writing comment you lot tin merely rename your method together with variable every bit 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 you lot are writing this slice of code, why you lot are writing this slice of code because this information is non visible until you lot write them inward comments together with this is critical to position whatever põrnikas or deportment amongst changing trouble concern environment.

4) If you lot are writing meat libraries which volition hold out 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 close writing Java-doc comment inward his classic Effective Java, which is worth knowing.

5) Include JIRA Number together with description on comment, especially if you lot are modifying an existing slice of code every bit business office of maintenance. This I establish extremely useful piece comparison unlike version of code inward CVS or SVN. This gives you lot clear thought why that particular code has been added together with whether consequence is because of that slice of code or not.


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

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

8) Always put comment piece committing code inward source command repository together with peculiarly why you lot are adding this slice of code if possible include JIRA or QC Number thence that whatever i tin refer JIRA for consummate details.

9) If you lot desire upcoming developer to follow certainly standards or inform close certainly things thence include them inward the start of your bird every bit comment. E.g. suppose if you lot are writing serializable bird inward coffee thence its proficient to seat a serializable warning stating that whatever novel fields add-on inward this bird must implement serializable interface inward java or move inward transient etc.


10) Last but non the to the lowest degree hand your code to immature human being 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 part 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

Sumber https://javarevisited.blogspot.com/

Share this post