Python/Java bad and good code comments examples

John D K -

In this article are shown the sins of comments and programming. You will see good and bad examples and what how can you write better comments.

You can see the video tutorial on this link: Python/Java bad and good code comments examples

The golden comment rule

Comments should be short and expressive. I prefer a few valuable comments instead of hundreds of useless lines. The comments should express the "why" and not the "what". The comment should be easily understandable by another person or even from the author(after some time). Good comments shouldn't outstand the code and shouldn't be use as excuse for not working code. You can think for comments like a map:

  • if the map is to detailed you will be lost in details - too much time will be spend for obvious problems
  • if the map lack of important info them you can get lost and chose a wrong path

The sins of commenting code

It's difficult to list all problems and mistakes related to comments but I'll try:

  • over-commenting code
  • lack of comments
  • update the code but not the comments
  • misleading/controversy comment
  • obvious comments
  • comment just because you are obliged
  • Funny comments

Over-commenting Code

Many beginners are tempted to over comment their code. Putting great detail and information which is unnecessary. Sometimes they forget to put the real purpose of the code.

Bad Example(Java)

/* x is incremented by one
it is called pre-increment 
first increase the value of x
by 1 and then use it
*/
x++;

Good Example(Java)

//increase the counter in case of errors
x++;

Lack of comments

Code is self explanatory or Code is always better than comments are popular sayings which could be very bad for code quality. Lets think of triple embedded recursion calling external methods. And this is a real example from a real software product. Can you guess how long spend, the person who designed it, to find a minor bug? An hour, a day.. no - several days.

Bad Example(Groovy)

(0..<(mtrx*.size().max())).collect {
    mtrx*.getAt(it)
}

Good Example(Groovy)

// (1) get the max by mtrx*.size().max() (2) iterate from 0 to max 
//(3) combine closure and spread operator to get every element in column

(0..<(mtrx*.size().max())).collect {
    mtrx*.getAt(it)
}

Update the code but not the comments

Sometimes when programmers are limited by time or are just lazy they can do the stupid / self-explanatory / obvious change and forget to update the related comment. This could lead the great confusion in future.

Bad Example(Python)

# recursive Fibonacci
def fib(i):
    if i <= 2:
        return 1;
    else:
        f = fib(i-1) + fib(i-2)
        print('calc', i)
    return f
print(fib(6))

Good Example(Python)

# non recursive Fibonacci
class Fibon:
    old = 1
    fib = 1
    current = 1

    def next(self):
        print('calc', self.current , self.fib)
        newFib = self.fib + self.old;
        self.old = self.fib;
        self.fib = newFib;
        self.current+=1
        return fib;

fibon = Fibon()
while(fibon.current < 5):
    k = fibon.next()
print(fibon.fib)

If we leave the old comment we can mislead the maintainer of the code.

Misleading/controversy comment

Better not to use comment rather than misleading reviewers of the code with wrong description. Even you can lose tremendous amount of time for the reviewer who may try to find the black cat in the dark room(except that the cat is not there).

Bad Example(Java)

//decrease the counter
x++;

Good Example(Java)

x++;

Obvious comments

The first example is really close to this category. One more example for obvious and not needed comments

Bad Example(Python)

# looping in range from 0 to 9 and printing the value to the console
for x in range(10):
  print(x)

Good Example(Python)

# 0, 1 .. 9
for x in range(10):
  print(x)

Comment just because you are obliged

Sometimes comments are a requirement and you need to do comment. Many programmers are offended by forcing them to put stupid comments and they want to do sweet revenge in the code. Interesting example for this situation is the next

Bad Example(Python)

# useless comment. they force me do it
for x in range(10):
  print(x)

Good Example(Python)

# 0, 1 .. 9
for x in range(10):
  print(x)

Funny comments

Programmers are notorious for their lack of humor(at least in the other people eyes). In other programmers eyes they can be extremely funny and full with crazy jokes. Next example show real code comment made in the code:

Bad Example(Python)

# if you solve this problem I'll marry you
def solve_me():
    ...

Good Example(Python)

# complex logic. In case of problems contact Mr.X
def solve_me():
    ...

Bonus Resource

What are Conventional Comments? They are: Comments that are easy to grok and grep. In short the idea is to label the comments in order to save time and make them easier for processing. They are good for code reviews and PRs.