Comments are an of import business office of writing code not exclusively inwards Java but whatever programming or scripting linguistic communication yous use. At the same time, this is i of the most abused things every bit well. Both writing no comment together with writing likewise much comment is bad together with this has been highlighted past times many software gurus e.g. Robert C. Martin inwards his classic majority 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 portion amongst yous guys approximately 0f the dominion together with best practices I follow piece writing comments. Before that let's firstly run into what is the role of having a comment inwards the code? Why create nosotros request comment, isn't writing code is enough. Some of the people I convey met ever debate that nosotros are getting paid for writing code together with non comment :).
Anyway inwards my reckon nosotros all concur amongst each other that software pass exclusively 10% fourth dimension of its life inwards evolution together with balance of 90% inwards maintenance. This 90% business office of maintaining the code is where comment tin hand notice assist yous immensely. Since no unmarried developer stays till whole life of whatever production or software together with its oft novel people, who plant of already written code. These are the people who read the code together with non aware of why a surely slice of code has been written, hither comments tin hand notice assist them to sympathize code chop-chop together with believe me yous volition acquire lot of roses from that swain developer :).
Anyway long storey curt hither are approximately of the things I endeavor to follow piece writing code:
1) Focus on readability of code; assume that yous don't convey comments to explicate the code. Give your method, variables together with flat meaningful name.
2) Don't write what code is doing, this should live on left for the code to explicate together with tin hand notice live on easily done past times giving class, variable together with method meaningful name. For example:
4) If yous are writing heart libraries which volition live on used past times dissimilar projection together with amongst dissimilar 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 inwards his classic Effective Java, which is worth knowing.
5) Include JIRA Number together with description on comment, especially if yous are modifying an existing slice of code every bit business office of maintenance. This I constitute extremely useful piece comparison dissimilar version of code inwards CVS or SVN. This gives yous clear thought why that particular code has been added together with whether result is because of that slice of code or not.
6) Always endeavor to finish your comment inwards every bit few words every bit possible, i liner comment is best until its explaining "Why" business office together with can't live on replaced past times code itself. No trunk likes or has plenty fourth dimension to read longer comment.
7) Don't write storey inwards comment every bit your name, employee id, your subdivision etc because those information tin hand notice live on obtained from CVS commit information inwards instance somebody wants to know who has brand this change.
8) Always put comment piece committing code inwards source command repository together with specially why yous are adding this slice of code if possible include JIRA or QC Number hence that whatever i tin hand notice refer JIRA for consummate details.
9) If yous desire upcoming developer to follow surely standards or inform close surely things together with hence include them inwards the starting fourth dimension of your flat every bit comment. E.g. suppose if yous are writing serializable flat inwards coffee together with hence its proficient to seat a serializable alarm stating that whatever novel fields improver inwards this flat must implement serializable interface inwards java or become far 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 enquire 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 hand notice better together with it’s exclusively 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
Anyway inwards my reckon nosotros all concur amongst each other that software pass exclusively 10% fourth dimension of its life inwards evolution together with balance of 90% inwards maintenance. This 90% business office of maintaining the code is where comment tin hand notice assist yous immensely. Since no unmarried developer stays till whole life of whatever production or software together with its oft novel people, who plant of already written code. These are the people who read the code together with non aware of why a surely slice of code has been written, hither comments tin hand notice assist them to sympathize code chop-chop together with believe me yous volition acquire lot of roses from that swain developer :). Anyway long storey curt hither are approximately of the things I endeavor 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 together with flat meaningful name.
2) Don't write what code is doing, this should live on left for the code to explicate together with tin hand notice live on easily done past times giving class, variable together with method meaningful name. For example:
//calculates foursquare rootage 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 rootage using Newton-Raphson method together with instead of writing comment yous tin hand notice only rename your method together with variable every bit follows:public void squareRoot(int num){ rootage = num/ 2; piece ( abs(root - (num/ root) ) > t ) { r = 0.5 * (root + (num/ root)); } System.out.println( " rootage = " + rootage ); } 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 inwards comments together with this is critical to position whatever põrnikas or demeanor amongst changing concern environment. 4) If yous are writing heart libraries which volition live on used past times dissimilar projection together with amongst dissimilar 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 inwards his classic Effective Java, which is worth knowing.
5) Include JIRA Number together with description on comment, especially if yous are modifying an existing slice of code every bit business office of maintenance. This I constitute extremely useful piece comparison dissimilar version of code inwards CVS or SVN. This gives yous clear thought why that particular code has been added together with whether result is because of that slice of code or not.
6) Always endeavor to finish your comment inwards every bit few words every bit possible, i liner comment is best until its explaining "Why" business office together with can't live on replaced past times code itself. No trunk likes or has plenty fourth dimension to read longer comment.
7) Don't write storey inwards comment every bit your name, employee id, your subdivision etc because those information tin hand notice live on obtained from CVS commit information inwards instance somebody wants to know who has brand this change.
8) Always put comment piece committing code inwards source command repository together with specially why yous are adding this slice of code if possible include JIRA or QC Number hence that whatever i tin hand notice refer JIRA for consummate details.
9) If yous desire upcoming developer to follow surely standards or inform close surely things together with hence include them inwards the starting fourth dimension of your flat every bit comment. E.g. suppose if yous are writing serializable flat inwards coffee together with hence its proficient to seat a serializable alarm stating that whatever novel fields improver inwards this flat must implement serializable interface inwards java or become far 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 enquire 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 hand notice better together with it’s exclusively 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