posts - 293 , comments - 413 , trackbacks - 0

My Links


View Steve Michelotti's profile on LinkedIn


Tag Cloud


Post Categories

My Online Presence

Commenting code is an anti-pattern


I have just gotten involved in a project that has been around for a while but developed with a different methodology to the one I am used to. One of the first things I noticed is that there were very little comments if any in the project. When bringing this up with one of the other developers on the team he defended the position of having no comments because as a team they felt that comments were an anti pattern. The motivation was as follows…


1) We name our methods and parameters so that they have meaning…

    public class PersonWithComments
        /// <summary>
        /// Makes a person class
        /// </summary>
        /// <param name="name">This needs to be the full name</param>
        public PersonWithComments(string name)
In the above code snippet the parameter name actually requires the full name. By relying on the comment to get this information it is fairly easy for a developer to miss the meaning of what “name” requires. Compare this with the snippet below…
    public class PersonWithoutComments
        public PersonWithoutComments(string firstName, string lastName)

Because there were no comments, the developer had to rely on the naming of the parameters to indicate their intent.

2) Comments are not easily viewed/updated when refactoring…

The team regularly refactored their code, often refactoring many many times in a session. When refactoring it was found that often the meaning of the method would be tweaked / changed and so the comments associated with the method would behind. This led other developers in the team to not always be confident on the validity of the comments. This added an element of doubt to the comments.

3) Commenting tests is not an anti-pattern

While the team found commenting production code to be of no real use, commenting tests were treated totally differently. In the tests they would explain certain business rules and why that particular test was necessary.

The heated debate this design decision made

What I found interesting was when these ideas were presented to a group of developers there was uproar in the room. The majority of the developers were from a statically typed world (C#) and I was surprized how passionate they felt about the necessity of putting comments in their code….

So, if someone had presented the idea that commenting code was an anti-pattern I think my initial response would be to defend the need of comments – I have had 20+ years of having comment your code drilled in my head for this to be a gut response however after being exposed to the concept for a while and having some time to think about it I am now leaning to the side that says I agree – commenting code (production code / NB not test code) is an anti-pattern.

My motivation is this…

I live in a strongly / statically typed world. I understand the benefits of this. If you considered your c# code as all being checked by the compiler, then one of the few things the compiler is going to ignore will be your comments… they fall under the radar. Since I use refactoring heavily the fact that my comments can fall behind my code worries me. In fact if I go through all the projects that I have done in the past, 90% of my comments are now no longer relevant – and the portion that is I could have easily extracted to tests.

What are your thoughts?

Print | posted on Monday, September 12, 2011 11:44 AM | Filed Under [ Architecture ]



# re: Commenting code is an anti-pattern

ALWAYS ADEPT comments to new functuality.

In 6 months you have no idea what the code was about, so you need plain text to understand it again.
9/12/2011 11:54 AM | nix

# re: Commenting code is an anti-pattern

It's an ancient debate. I agree with the guy who said "Code says what, comments says why".
9/12/2011 12:07 PM | Onofrio Panzarino

# re: Commenting code is an anti-pattern

I agree with this:

Also for tests.
9/12/2011 1:47 PM | petrje

# re: Commenting code is an anti-pattern

only comment background knowledge (rarely). the code themself should be expressive enough (by breaking the code in small blocks (SRP) and usage of good names).
everybody who claims on comments doesnt use refactoring (otherwise he knows, that synchronisation from code to comment fails) and this lack is a deeply harder processing gap than missing comments)
9/12/2011 2:11 PM | Marko Apfel

# re: Commenting code is an anti-pattern

1. Code doesn't show *why* it's doing what it is.
2. There is sometimes a difference between what code *does* and what it is *supposed to do*.

In my experience, the developers that are not writing comments are those that never have to maintain other peoples code, or even their own. They write code and then throw it over the fence for others to mop up.
9/12/2011 3:21 PM | Danny Tuppeny

# re: Commenting code is an anti-pattern

+1 for "Code says what, comments says why".
9/12/2011 3:28 PM | Robert MacLean

# re: Commenting code is an anti-pattern

I agree with Onofrio Panzario and Mister Apfel.

In my case, the Unit Tests (done by TDD) usually sufficiently comment the why. Where this is not the case, i will add comments to the unit test or the code, which is rather rarely the case.
These are usually things which don't change often, and when, are not changed by a simple refactoring like rename...
Another advantage is, that comments are actually read when there are only few of them. If the code is cluttered with "Gets or Set [PropertyName]" kind of code, nobody will bother to read comments until it's too late.
9/12/2011 4:26 PM | Bruno Juchli

# re: Commenting code is an anti-pattern

I agree with Onofrio; it's an ancient debate. The best conclusions I've been able to reach with regard to commenting being an anti-pattern are: 1) Code that requires comments may indicate the existence of anti-patterns upstream in the development process, such as poor naming conventions. 2) Rigid commenting requirements can be a development anti-pattern. For example, I once worked for a boss who decided that every line must be commented. I mean that literally: every line of code required a comment. You can guess what happened to productivity.
9/12/2011 5:24 PM | TechNeilogy

# re: Commenting code is an anti-pattern

I used to feel quite strongly that code comments were unnecessary. With a bit more experience I have found that there is no absolute truth and code can never be so beatiful that it surpasses a clear explanation.

I do follow a few rules however: Favouring javadoc improves the IDE and other tools abilities to use the comments as generated documentation or to show in hover-over tool tips. "In method" comments can usually be replaced by refactoring some code into a method.

Cection comments to let the reader know that the next section of text is helper methods or something else usually means that the code should be in a different class.

Use @link wherever possible for class, method and field names. If you do this then eclipse will change the comments when it refactors the names.
9/12/2011 5:47 PM | Andy Till

# re: Commenting code is an anti-pattern

I think code tells us always two things, WHAT is being done, and HOW its being done.

If we name our methods , parameters and variables using good names, and avoid mixing in our functions several levels of abstraction, then the comments can only be useful to say WHY something was done in a certain way.

The HOW is already in the name of the functions etc, si I agree that comments tend to be mostly not helpful in production code.

Comments in tests are great to describe the scenario being tested, like a test plan. This usually only makes sense for integration tests.

When coding I look for the opportunity to replace a comment with a function call with a meaningful name, it leads to more readable code.

By reading the names of the methods and variables we should quickly be able to get WHAT is going on, otherwise we need to read the whole thing and deduct the WHAT from the HOW.

Then again i work in a project where we are obliged by contract to comment the whole public API, including all getters and setters :-)

Gladly intellij has a plugin to generate getters and setters already commented, in both russian or english :-)

9/12/2011 11:31 PM | XPTO

# re: Commenting code is an anti-pattern

I don't think comments are necessary for the most. But then I feel quite confident about reading code, even bad code, and working out both what and why.

The times I use comments are unit tests and documenting non obvious interactions with external systems. Which comes up a bit in embedded systems where you have to do weird things at times to make the hardware work.

in the world of C# I hardly ever feel I need comments.
9/13/2011 1:30 AM | Keith Nicholas

# re: Commenting code is an anti-pattern

Long, unbreakable lines with fixed-width font that forces you to scroll horizontally to read the page is a Web anti-pattern... :-)
I often saw this stance (no comments) and I find it a bit extreme.
I agree that names must be significant, although with a limit (50 char names aren't very usable...). In most cases, they should explain the code. But sometime, you have to justify why you chose this algorithm or such trick, because otherwise somebody will "correct" it and break the solution.
Sometime, you have to explain what a class is doing, how it fits in the global picture, what is its role.
Sometime, you just have old, legacy code, that needs to be sprinkled with explanations, because there is just no global documentation of the architecture.
Indeed, sometime comments gets unsynchronized with code, but that's laziness or short-sighting from the developer, not the comment's fault...
Personally, I highly appreciate to be able to hover over a method or class name in Eclipse, and to have a bit more information of what the name can provide. That's why doc-commenting even private methods is useful...

Now, of course, the other extreme is annoying too, explaining what i + 4 adds 4 to i is just noise, same for comments on (most) accessors, etc.
9/13/2011 12:26 PM | PhiLho

# re: Commenting code is an anti-pattern

Right! comments are for people not for compilers comment so you help yourself understand what you are doing and in this way, others my benefit from it as well.

In the same way that you should code to interfaces not implementations, you should comment to intent, not concrete declarations.

Also: if you refactor the code in a way that breaks the comments..simple: update your comments as and when you see this has happened..we should be lazy programmers in a positive productive way, adding the right comments in the right places allows me to be just that, lazy in having to go through the pain of figuring out what the code does and helps me realize if its doing it right.

Your code is not complete if you cannot read the intent easily.

Complex does not mean complicated, sometimes a comment like "I am assuming [....]" or "<returns>what I think should return</returns>" can shave off refactoring/updating/debugging code time by hours and hours, not to mention, being able to go back to the requirements list and checking if these have changed since the time of initial conception.

Finally: When the method name is not intuitive like "Add" or "Submit" and then goes off to just insert a new row or open up a window. Yes, the method name should be made more intuitive, but sometimes its harder to change a method name (which may even keep changing again and again, but perform something towards the same goal every time) than it is to add the appropriate semantics to the method in code.
9/13/2011 12:39 PM | Ric Santos

# re: Commenting code is an anti-pattern

I have been having the same though lately about simple classes and methods that are well-named so that their purpose is obvious from the names alone.

However, whenever I code anything that has complex unobvious behaviour I always put detailed comments in the code (eg: tricky business logic, code optimized to do the least number of calculations to reduce CPU usage which is not intuitive to a human viewer, etc.).
12/17/2011 3:25 AM | Kevin
Post A Comment

Powered by: