How Often Should You Have Comments In Code?

comments in code

Comments in code is such an endless debate, so much so that I couldn’t help but share my own arguments on it. So, where do I really stand as far as comments in code is concerned? Hold it for a second. In his best-selling book Clean Code, Uncle Bob, makes the following analogy while talking about clean code :  as location is to real estate, so is readability to source code. I totally agree with that statement. With that in mind, let us take a look at some arguments for and against having comments in your code.

There are several arguments for and against having comments in code. Let us start with the reasons why you should refrain from commenting your code:

What having comments in code could mean

  • A sign of bad programming – in short, you are not a good programmer! That is a tough pill to swallow. It could be totally wrong but you know the truth about how good you are as a software developer. By commenting all over the place, you are exposing your insecurities as a programmer.
  • Laziness – you leave a lot of comments in code when trying to explain what the code does. You should instead write code that explains what it does; in other words, you are running away from responsibility. Variable names, methods and class names should read like a well-written column. Should say what they do.
  • Unless your code is a public-facing API, your coding style is probably bad. Again, who am I to judge? The truth however is this: unless you are writing an API that users will have to read through its documentation to use it, having comments everywhere a method is defined is just unnecessary. Adds to the line numbers and crowds the class file.
  • You are a procrastinator. Commenting code so that you can come back later to fix something or do it right is a bad idea. The best approach in such a situation is to get it done today or before moving on to the next part of code project.
  • Commented-out code – the reason why version control tools exist today is to take away the responsibility of remembering changes from you and me. Commented out code is ugly and should be deleted. If you want to get it back, just get it from your version control system.

When you can have comments in code

You are probably thinking “shut your face Elisha”, how can I not have comments in my code? You are right; you should have comments in your code – at least when you cannot avoid it. Here are the situations that could warrant having comments in code.

  • Public Facing API – without comments, you cannot generate documentation. That means your API will be difficult to use by other developers. If you have tried using a library that does not have documentation, you know what the heck am talking about.
  • Possibility of something dangerous happening. Perhaps you want to warn a future reader of your code about the risks of executing some code under certain conditions or environments. It really comes down to you; if you spent enough time to think about your code, you wouldn’t need to warn people of your code’s possible explosions.
  • Header comments – always on top of the file. I like this because you always get the opportunity to include your name. It shows a sense of responsibility. If you write crappy code, (I hope you don’t), another programmer can easily locate you – they know who you are because you are not a coward. Take some responsibility. Be awesome!


I know for a fact that being told I am a bad programmer is not the compliment I would like to hear, not even from my grandma. The fact is, you have a “way” of writing code and you hold it dear. You believe it is the “right” way just as I do whenever I write code everyday. But what is right and what is wrong about having comments in code? Who calls the shots? I think using your own judgment and learning from experts like Uncle Bob and Steve McConnel can help you see what you are missing.

If you have been flooding your code with comments, do not feel bad. Just re-factor it slowly by slowly. You might even learn a thing or two about writing clean code – just like I did.

That is all I have to say today! If you found this post helpful, please consider sharing it using the buttons below. Thank you and always stay awesome as you write clean code – code that says what it does. See you!

NOTE: If you have not read Uncle Bob’s Clean Code, I highly recommend it. I have no affiliation to the seller of the book.

Written By Elisha Chirchir

Elisha Chirchir is a software developer. He is also the founder of Simple Developer and co-founder of Instinctive Software Solutions. On any given day, he works on both Android and Web Development. During his 'free time', he offers training to those interested in learning how to code in php, java, python, javaScript etc. You can easily find him on StackOverflow Android chatroom or on Twitter @Eenvincible

10 Comments on “How Often Should You Have Comments In Code?

  1. Melvin Reply

    August 14, 2014 at 4:59

    When I was freelancing, I rarely commented my code because generally I was the only one working on it. But now that I work for a large company, where sometime the business owner(s) have requests that almost force me to write obscure conditional statements, I find commenting my code save me a lot of time while supporting the application.

    • Elisha Chirchir Reply

      August 14, 2014 at 5:59

      So you were sure that no one else would ever read your code then?

  2. Jeff Szuhay Reply

    August 14, 2014 at 8:46

    I think your example is had; those comments are obvious to what the code does and are superfluous.

    Ever try to read a book and an a poem at the same time? That’s what sprinkling your code with redundant comments is like.

    When I write comments, I generally to the following:
    1. Describe the general algorithm/heuristic in the function header. Same goes for describing a class.
    2. Assume the reader understands 90% of the language. This means to sometimes point out unusual or quirky uses of the language; it does not mean trying to teach the reader the language.
    3. Make explicit edge cases, or unusual process states that the code is/is not addressing.

    Apart from that, details of commenting style, spacing, and placement all really depend upon the language and its environment.

    • Jeff Szuhay Reply

      August 14, 2014 at 9:03

      Here’s how I’d have commented that code:

      public class HelloAgain

      // print out 10 "Hello" strings counting them ordinally.
      // The first 3 ordinals don't end in "th".
      // The rest end in "th" so using a while loop.
      // NOTE: args parameter not used.

      public static void main( String[] args ) {

      System.out.println( "1st Hello" );
      System.out.println( "2nd Hello" );
      System.out.println( "3rd Hello" );

      int i = 4;
      while( i <= 10 ) {
      System.out.println( i + "th Hello" );
      i = i + 1;

      Notice that the comments focus on the intent of the overall method and the code speaks for itself.

  3. John Burton Reply

    August 15, 2014 at 2:59

    It is easy to see WHAT this code is doing, but WHY????

    What is this code trying to achieve?
    – Are you trying to alert the user by repeatedly outputting the hellos?
    – Is it to show that the thread is still alive?
    – Are you trying to demonstrate the difference between numeral postfixes?
    – Do you just need a 10 line padding in your output, so that the screen format lines up cleanly?
    – Is this just a dummy function so that you know that a point in code was reached, and you will delete it later?

    Why is it called “HelloAgain” – what does that mean?
    Shouldn’t this be ‘ShowHellosOnConsole”?

    Why is it 10 times and not 20? Is the number 10 important? If I change 10 to 15, will the output format be ruined? Will something else scroll off the top?

    Why is it System.Out and not a stream? Or a log function like the rest of the system?

    This output is interfering with the output on my other thread, and I need to port everything over to streams – Can I just remove it?

    Who can i ask?
    Oh, where is the developer…has anyone got his phone number?….

  4. Bobby Hubbard Reply

    August 15, 2014 at 3:03

    You have way over-simplified and generalized software development. My guess is that you have never worked on a large multi-commiter project before… Or had to pick up a legacy app and add a feature request or maintain it for any given amount of time. If you had you might instead say:
    * you can tell the difference between a naive, great developer and seasoned, great developer by their comments
    * comments should add context and clarity to already readable code
    * if I want to know what your class does, I read the code. If I want to know why, I look for comments. (I’m not talking about functional ‘why’…but implementation specific why.)
    * like has already mentioned…comments explain awkwardness due to something out of the authors control.
    * comments justify weird rules. (Eg “see JIRA-12. Mis-spelled due to manufacturing error”)
    * comments highlight areas of complexity and potential traps.

    Etc etc. I work with some of the best IMO and they all comment too little. I don’t want a repeat of what the code already tells me…I want the next dev be able to pick it up and roll with NO questions.

    Comment more but only if you are going to comment better.

  5. Martin Reply

    August 15, 2014 at 9:39

    @Jeff Szuhay

    You could write your code like this:

    import java.util.*;
    import java.lang.*;

    class HelloAgain {

    public static void main( String[] args ) {
    printTenHelloWithCounting ();

    private static void printTenHelloWithCounting() {

    private static void printFirstThreeHello(){
    System.out.println( “1st Hello” );
    System.out.println( “2nd Hello” );
    System.out.println( “3rd Hello” );

    private static void printRestHellos(){
    int i = 4;
    while( i <= 10 ) {
    System.out.println( i + "th Hello" );
    i = i + 1;

    There is no need to explain that you use a whileloop to count from 4 to ten. Btw: if you change your implementation to a for loop, you have to take care of your comment

  6. Lucho Reply

    August 15, 2014 at 2:40

    Hi, I’m not totally agree with you. I shouldn’t spread comments all over the code like in the example you made. But simple comments that explain the intention, or what is being done at the beginning of block of code helps someone who never read it to be up and running in short time.
    Besides I should make readable code, I think is simpler to read a statement of intention in human language that any programming language.
    Am I wrong?

    ps: sorry about my english

  7. Filip Hanik Reply

    August 18, 2014 at 3:32

    I would have to disagree on all the points mentioned in “What having comments in code could mean”

    All five points are based on the fact that “I” as a programmer, put in comments for “myself”.

    Take a look at the class in the JVM. Clearly the comments are not put in place cause Doug Lea is lazy or insecure or a procrastinator.

    These comments are not for the ‘public API’ reason, that is what JavaDoc is for. The comments are for developers trying to understand the underlying code.

    The comments are for other programmers. And that is what comments are four. They are only exposed to those that read the actual source code.

    Concurrent programming can be very difficult to read . Bit manipulating code may be even worse. Any type of low level code should have a lot of comments.

    There are API’s that are very difficult to use. For example java.nio socket programming is not an easy task. As you write your code, there is no way, three months later you can remember all the intrinsic details of the API that you just used. Comments can save you hours, and prevent another programmer to make changes resulting in bugs that you encountered yourself

    Comments have their uses, and they are definitely not a sign that you are a bad programmer.

    • Bobby Hubbard Reply

      August 18, 2014 at 9:24


Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.