Pages

Wednesday, March 21, 2012

10 Best Practices of Code Commenting & Formatting





Code commenting and formatting are all about code understandability. Code understandability is very relevant to code maintainability. So, small details about programming may help maintainability. In this context, some practices about commenting and formatting will be told here:

Commenting

Comments may be thought as part of the code, so they are really important. E.g. a commentless code library will be useless in a short time with high probability. Even though there are some approaches which suggests self-documenting code over code documentation, we suggest (self-documenting code + code documentation).
  1. Use comments "as required". 
    • Unnecessary over-commenting in each line will reduce readability:
      • int count = 0; // assigning zero as initial value to the count (?!?)
    • Lack of commenting will increase maintenance time. Also, variable/method names should be understandable and self commenting
      • int s = sqrt(v1) + v2 / v3 + fread(s). getChar(0)  //(?!?)
      • List<int> getVal(int val, int len, String op) //(?!?)
  2. Don't write uncorrect comments. Uncorrect explanations are worse than no-comment. 
  3. Write comments for variables which are important and non-selfdocumenting.
  4. Writing comments (e.g. JavaDoc declaration) for all public methods is a good practice. Of course, these comments should be "really necessary" and "as required".
  5. Document "gotcha"s and "todo"s instantly when detected. These items may be remembered for that day but may not for tomorrow when not documented, so a buggy code will be inevitable.
Formatting

Formatting rules can be detected automatically by most tools (e.g. maven checkstyle) and applied automatically by most IDEs (e.g. Eclipse Code Formatter ctrl+shift+f). But there may be little differences between company formatting rules, so these tools should be configured before applying formatting.
  1. Use brackets consistently. You may choose opening a bracket at the end of the current line or at the beginnning of the new line. Choose one of them and use consistently in the whole application.
  2. Use blank lines consistently and as required. Blank lines may be used for separating  code lines or line groups semantically for readability. E.g. 3 blank lines at the end of a method, no-blanks on whole code or one or two blank lines between each line of code reduces readability and not good for eye pleasure.
  3. Pay attention for indentation. Correct indentation for grouping statements is as important as using brackets and blank lines.
  4. Character count of a line should be limited for readability. This limit is generally 80 for most developers, but may change a little due to some other development parameters. 
  5. Using space chars in code should also be consistent in whole application. Generally, situations below are suitable for using spaces:
    • Between operators and operands: 
      • a += b , c = 0; (a == b)
    • Between statement keywords and brackets: 
      • if (value) {, public class A { 
    • After ';' char in loops: 
      • for (int i = 0; i < length; i++) 
    • Between type casters and operands: 
      • (int) value , (String) value


7 comments:

  1. Frankly, you should write your code that it can be read as good book.
    For me usage of comment is lack of good design.
    If your design is good you don't have to explain anything.

    ReplyDelete
  2. Nothing is as best as code speaking for itself but still comments can add value by writing "why you are doing" or "why you are doing in that way". comment which describe "how" part is useless as that would be obvious form code. Also something specific, not intuitive demands comments. here are few more code comments best practices which helps

    ReplyDelete
  3. Anonymous - Any coder who says that use of comments is lack of design is any or all of the following:

    (a) Not really a coder.
    (b) A hobbyist who has never worked with a significant code base.
    (c) Has never worked on legacy code or code written by someone else.
    (d) Has never worked on a team.

    Code alone will NEVER explain WHY something is the way it is. All it can do is tell you WHAT.

    Any coder working on my teams had better have a good commenting strategy otherwise they don't last.

    ReplyDelete
  4. I have worked on a team, and make a living as a programmer. Among other things, I have also done maintenance work on legacy code - and hated it. Comments didn't help there.

    IMO, the only reasonable place to write comments is in implementation where you do something non-obvious. If you need comments elsewhere, your code is not self-describing, and you should improve it.

    As for the why, I do agree, but that's the part of documentation which doesn't have its place in code. For the most of it, the why should essentially be verifiable by your customer, and I doubt your customer is able and willing to read code in most cases.

    ReplyDelete
  5. Heya¡­my very first comment on your site. ,I have been reading your blog for a while and thought I would completely pop in

    Appear fervent about it. I’m developing a fresh blog plus I’m struggling to make it look good, as well as offer the best

    quality content. I have learned much at your web site and also I anticipate alot more articles and will be coming back

    soon. Thanks you.


    Journal Editing and Formatting Service

    ReplyDelete
  6. You should never comment code, you document it. Any company worth its salt will have a system designed for documentation and documentation standards. Which should explain when, where and why you document code.

    "Well written code can be self-explanatory, so heavily commented code can indicate poor code quality. Unit testing can be better than commenting to show how code is intended to be used. Modifications and authorship can be reliably tracked using a source-code revision control system, rather than using comments. Comments can add a development and maintenance overhead."

    http://en.wikipedia.org/wiki/Best_Coding_Practices#Commenting

    ReplyDelete
  7. And that is from someone who has gone through many legacy systems. Nothing more annoying to have to skip over 100 lines of comments to look at 10 lines of code, only to have to skip over another 100 lines of comments...

    ReplyDelete