Click here to Skip to main content
13,630,702 members
Click here to Skip to main content
Add your own
alternative version

Tagged as

Stats

13.2K views
5 bookmarked
Posted 2 Feb 2015
Licenced CPOL

Code Comments are Lies

, 2 Feb 2015
Rate this:
Please Sign up or sign in to vote.
Although there are use cases for comments, I am going to tell you that comments are like little poops that you leave all over your code for your fellow devs to step in.

Update

As is evident in the comments, my intent for this post did not come across. 

  1. This post is aimed at higher level languages like C# and Java. Please comment your FORTRAN, etc.
  2. The best code that you can write is code that is maintainable as this is the true cost of software. If this requires you to add a comment, please do that. I also do that.
  3. A comment as an excuse for writing bad code, is unacceptable. 

Please read the comments for some valuable use cases for comments.


I'm going to make a bold statement.

YOUR COMMENTS ARE BAD AND YOU SHOULD FEEL BAD

We got a Bad Ass here

"Oh no he didn't". "My comments are informative and well written." "How else would people understand this awesome piece of efficient code?"

Although there are use cases for comments, I am going to tell you that comments are like little poops that you leave all over your code for your fellow devs to step in.

Let's Look At Some Truths About Comments

  • They can state the obvious, thus being redundant.
//The Persons First Name
public string FirstName { get; set;}
  • Having comments scattered throughout your code, explaining functionality in detail, makes it hard to read code fluently. This means that extra effort and concentration is needed to read between the comment lines. The intent does not jump out at you.

Comments Become Lies

  • Comments rarely get updated when the code changes. This means that overtime the functionality documented by the comments, drifts away from what is actually happening. This causes confusion and again makes the comments worthless.

  • ToDo Comments. They usually don't get done.

  • Comments get copied with code, and as the code changes again, the comments don't. First of all, you should think twice when you need to copy code, and if you have a great reason, you have to make real sure to update (or even just remove) the comments made.

  • Finally, like Uncle Bob says in his book Clean Code, if you need to write a comment, you have failed to express the intent of the code. You want your code to read well, to be self-documenting so that you do not need to document it.

I have written all these types of comments.

I need to write a comment about my code, thus I have failed.

This is another bold statement. But it is exactly what I tell myself when I need to write a comment. It forces me to rethink my code and usually rewrite it to be more readable and maintainable. And if I still need to write the comment, it reminds me that I still have room for improvement. I can decide to leave out the comment and not feel bad, but I write it in the hopes that it might aid me or whoever comes after me to understand my poorly expressed code.

So What Can I Do To Fix This Problem?

First of all, Name Things Well. Well named classes and functions and properties help eliminate confusion and clarifies code intent. A function should do what it says, a class be what it is named.

Functions should do one thing, it should do it well and it should do it only. Following the Single Responsibility Principle will eliminate most reasons to comment code.

But I hear you shouting from afar: "Pieter, not all comments can be bad". This is true, although I still maintain comments are bad.

Some Good Comments

  • Comments that you write to document badly written legacy code. It is not always possible to refactor code, so in these cases help yourself and others to document things that might have bad side effects.

  • Comments documenting framework limitations.

public FooConstructor()
{
    //EntityFramework requires a default constructor
}
  • ToDo comments can be a great way to remind yourself of something that you need to do. Only use them while working on feature branches. They should be implemented or removed (placed on your backlog as a ticket) once you merge back to your main branch.

  • In the rare case that you need to write optimised code that might be confusing and not easily readable. This is a rare case for most of us.

  • API documenting code. In some languages, you can add comments to classes, methods and properties and these will get rendered by your IDE or can be exported to actual documents. This should only live on public facing code and has no place inside your application where some random user will not use it.

Remember you want to write readable, self-documenting, maintainable code for yourself and others. So stop writing that comment and be awesome instead.

If you can think of other examples, please add them in the comments and if you liked this post, share it with the hashtag #badcomment. For those of you that are still angry, here are some funny comments.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

Share

About the Author

SneakyPeet
Software Developer (Senior)
Unknown
I write about Domain Driven Design, Clean Code and .net

You may also be interested in...

Pro

Comments and Discussions

 
QuestionAgreed Pin
Sander Rossel14-Mar-15 8:50
professionalSander Rossel14-Mar-15 8:50 
GeneralMy vote of 2 Pin
KarstenK12-Mar-15 23:32
memberKarstenK12-Mar-15 23:32 
Question[My vote of 2] What about The Why? Pin
John B Oliver26-Feb-15 11:02
memberJohn B Oliver26-Feb-15 11:02 
AnswerRe: [My vote of 2] What about The Why? Pin
SneakyPeet26-Feb-15 19:22
memberSneakyPeet26-Feb-15 19:22 
GeneralRe: [My vote of 2] What about The Why? Pin
John B Oliver1-Mar-15 9:38
memberJohn B Oliver1-Mar-15 9:38 
Question//TODO: enhance useful comments Pin
KarstenK4-Feb-15 6:34
memberKarstenK4-Feb-15 6:34 
AnswerRe: //TODO: enhance useful comments Pin
SneakyPeet4-Feb-15 9:20
memberSneakyPeet4-Feb-15 9:20 
QuestionI don't agree with everything you've said... Pin
CHill604-Feb-15 0:57
protectorCHill604-Feb-15 0:57 
General[My vote of 1] TODO: Clean Up Your Act Pin
jediYL3-Feb-15 17:20
memberjediYL3-Feb-15 17:20 
GeneralMy vote of 2 Pin
BeastSS3-Feb-15 12:29
memberBeastSS3-Feb-15 12:29 
Question[My vote of 2] What about my comments that HINT to PhpStorm how to understand my variable types? Pin
Kirk 103898213-Feb-15 11:40
memberKirk 103898213-Feb-15 11:40 
AnswerRe: [My vote of 2] What about my comments that HINT to PhpStorm how to understand my variable types? Pin
SneakyPeet3-Feb-15 17:56
memberSneakyPeet3-Feb-15 17:56 
QuestionTrue Too Often Pin
Ken Utting3-Feb-15 11:02
memberKen Utting3-Feb-15 11:02 
AnswerRe: True Too Often Pin
SneakyPeet3-Feb-15 18:02
memberSneakyPeet3-Feb-15 18:02 
QuestionWhat a load of baloney! Pin
Bob10003-Feb-15 10:26
memberBob10003-Feb-15 10:26 
AnswerRe: What a load of baloney! Pin
SneakyPeet3-Feb-15 18:06
memberSneakyPeet3-Feb-15 18:06 
QuestionCode Comments are Lies...are an excuse for sloppy practices Pin
Member 110348063-Feb-15 8:59
memberMember 110348063-Feb-15 8:59 
AnswerRe: Code Comments are Lies...are an excuse for sloppy practices Pin
Member 110723443-Feb-15 10:53
memberMember 110723443-Feb-15 10:53 
GeneralRe: Code Comments are Lies...are an excuse for sloppy practices Pin
Kirk 103898213-Feb-15 11:48
memberKirk 103898213-Feb-15 11:48 
AnswerRe: Code Comments are Lies...are an excuse for sloppy practices Pin
SneakyPeet3-Feb-15 17:52
memberSneakyPeet3-Feb-15 17:52 
GeneralRe: Code Comments are Lies...are an excuse for sloppy practices Pin
_Asif_3-Feb-15 20:58
professional_Asif_3-Feb-15 20:58 
AnswerRe: Code Comments are Lies...are an excuse for sloppy practices Pin
theBulldog_314-Feb-15 4:48
membertheBulldog_314-Feb-15 4:48 
GeneralRe: Code Comments are Lies...are an excuse for sloppy practices Pin
SneakyPeet4-Feb-15 9:19
memberSneakyPeet4-Feb-15 9:19 
GeneralRe: Code Comments are Lies...are an excuse for sloppy practices Pin
PeejayAdams6-Feb-15 3:23
memberPeejayAdams6-Feb-15 3:23 
GeneralRe: Code Comments are Lies...are an excuse for sloppy practices Pin
SneakyPeet6-Feb-15 7:34
memberSneakyPeet6-Feb-15 7:34 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

Permalink | Advertise | Privacy | Cookies | Terms of Use | Mobile
Web04 | 2.8.180712.1 | Last Updated 2 Feb 2015
Article Copyright 2015 by SneakyPeet
Everything else Copyright © CodeProject, 1999-2018
Layout: fixed | fluid