10 Best Practices To Follow Field Writing Code Comments

Comments are an of import role of writing code not solely inwards Java but whatever programming or scripting linguistic communication y'all use. At the same time, this is i of the most abused things every bit well. Both writing no comment in addition to writing likewise much comment is bad in addition to 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 in addition to finding pros in addition to cons of comment. This article is my learning inwards the same direction, hither I am going to portion amongst y'all guys about 0f the dominion in addition to best practices I follow spell writing comments. Before that let's foremost encounter what is the role of having a comment inwards the code? Why create nosotros take away comment, isn't writing code is enough. Some of the people I accept met ever fence that nosotros are getting paid for writing code in addition to non comment :).


Anyway inwards my persuasion nosotros all concur amongst each other that software pass solely 10% fourth dimension of its life inwards evolution in addition to residuum of 90% inwards maintenance. This 90% role of maintaining the code is where comment tin compass notice assist y'all immensely. Since no unmarried developer stays till whole life of whatsoever production or software in addition to its ofttimes novel people, who plant of already written code. These are the people who read the code in addition to non aware of why a sure enough slice of code has been written, hither comments tin compass notice assist them to sympathise code chop-chop in addition to believe me y'all volition acquire lot of roses from that beau developer :). 

Anyway long floor curt hither are about of the things I try to follow spell writing code:

10 tips on writing code comments

1) Focus on readability of code; assume that y'all don't accept comments to explicate the code. Give your method, variables in addition to bird meaningful name.

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

//calculates foursquare rootage of given number 

//using Newton-Raphson method

public void abc(int a){

       r = a / 2;

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

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

       }

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

}

Above code is calculating foursquare rootage using Newton-Raphson method in addition to instead of writing comment y'all tin compass notice simply rename your method in addition to variable every bit follows:

public void squareRoot(int num){

       rootage = num/ 2;

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

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

       }

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

}

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 in addition to this is critical to position whatsoever põrnikas or behaviour amongst changing trouble organization environment.

4) If y'all are writing inwardness libraries which volition endure used past times dissimilar projection in addition to amongst dissimilar teams. Follow javadoc comment style in addition to document all supposition in addition to precondition for using your API. Joshua Bloch has also mentioned virtually writing Java-doc comment inwards his classic Effective Java, which is worth knowing.

5) Include JIRA Number in addition to description on comment, especially if y'all are modifying an existing slice of code every bit role of maintenance. This I constitute extremely useful spell comparison dissimilar version of code inwards CVS or SVN. This gives y'all clear thought why that particular code has been added in addition to whether resultant is because of that slice of code or not.


6) Always try to finish your comment inwards every bit few words every bit possible, i liner comment is best until its explaining "Why" role in addition to can't endure replaced past times code itself. No torso likes or has plenty fourth dimension to read longer comment.

7) Don't write floor inwards comment every bit your name, employee id, your subdivision etc because those information tin compass notice endure obtained from CVS commit information inwards instance somebody wants to know who has brand this change.

8) Always put comment spell committing code inwards source command repository in addition to peculiarly why y'all are adding this slice of code if possible include JIRA or QC Number thence that whatsoever i tin compass notice refer JIRA for consummate details.

9) If y'all desire upcoming developer to follow sure enough standards or inform virtually sure enough things in addition to then include them inwards the outset of your bird every bit comment. E.g. suppose if y'all are writing serializable bird inwards coffee in addition to then its skillful to set a serializable warning stating that whatsoever novel fields add-on inwards this bird must implement serializable interface inwards java or acquire far transient etc.


10) Last but non the to the lowest degree compass your code to beau developer to understand every bit role of code review in addition to inquire him how much he understands it.

That’s all from me on code commenting, delight portion 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 compass notice ameliorate in addition to it’s solely 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

Bagikan Artikel ini