Agile FAQs
  About   Slides   Home  

 
Managed Chaos
Naresh Jain's Random Thoughts on Software Development and Adventure Sports
     
`
 
RSS Feed
Recent Thoughts
Tags
Recent Comments

Are comments Evil?

Today @Directi we had a few freshers from Universities come down for an interview. As part of the interview process, I presented on Code Smells. During this I was thrashing the whole “write good comments” universal best practice.

During this Ramki was sitting and he silently wrote me an email asking “Are comments evil?” His email follows:

Naresh,

Can you please opine if comments are bad in the following scenario:
(For this project dojo is a dependency and is not owned/maintained by the guys using it to write this code)

this.show = function(){
    this.view.show();
    //this is a hack, dojo seem to have an issue in rendering
    //dynamically/programmatically generated widgets.
    //We *should* call resize() to ensure that the widget is appropriately rendered
    this.view.resize();
}

—- Vs. ——-

this.show = function(){
    this.view.show();
    this.view.resize();
}

In the later case where comments are removed or say never written, though the user understands that you are resizing he would still be wondering why am I calling resize() when I am just showing..?

This is a great question Ramki.

I always say that comments are evil and we should not write comments. Also the first thing I do when I see some code is delete all the comments in it. This is an over generalized comment.

What I really mean:

Writing comments that explain “how” or “what” is evil. Comments (esp. about what and how) is a clear failure to express the intent in code. Comment is a deodorant to hide that failure (smell). However sometimes “the why” is not apparent and if you don’t find a suitable way to communicate that through code, comment is the fall back option. Note that comments are a fall back option rather than a default option. More on this…document the why.

At times, one has to think hard to write code that expresses intent rather than write some sloppy code with poor abstractions and get away by writing comments.

In my Self Documenting Code blog I show a similar example and explain the thinking process.

In case of your code I could write it as follows:

this.show = function(){
    this.view.show();
    reRenderDynamicallyGeneratedWidgets_dojoHack(this.view);
}
 
function reRenderDynamicallyGeneratedWidgets_dojoHack(view){
    // Link describing this bug and the workaround.
    view.resize();
}

This is really pushing it, but I hope you understand where I’m heading with this.

  • http://cbas.pandion.be/ cbas

    IMHO you essentially put the comment in the name of a function. Since this is JavaScript it’s likely there will be many cases where intellisense is not available to the developer, making it error-prone to type such lengthy names.

    Also, why introduce a function that contains only one line of code and will be called only from that location? Feels like SLOC-bloat that makes the code slower and less readable where a comment would have sufficed.

    0.02

  • http://cbas.pandion.be/ cbas

    IMHO you essentially put the comment in the name of a function. Since this is JavaScript it’s likely there will be many cases where intellisense is not available to the developer, making it error-prone to type such lengthy names.

    Also, why introduce a function that contains only one line of code and will be called only from that location? Feels like SLOC-bloat that makes the code slower and less readable where a comment would have sufficed.

    0.02

  • http://andypalmer.com Andy Palmer

    I cover similar ground to this in What should my code tell me
    Comments should represent hard won pieces of knowledge, like the re-rendering issue, where a function to represent that may be overkill (remember that someone may refactor the method name later, without understanding the intent behind the method name)

  • http://andypalmer.com Andy Palmer

    I cover similar ground to this in What should my code tell me
    Comments should represent hard won pieces of knowledge, like the re-rendering issue, where a function to represent that may be overkill (remember that someone may refactor the method name later, without understanding the intent behind the method name)

  • Peter Bindels

    Any comment you type should tell you the reason why the code is the way it is and why it should or should not be changed to something else. In the case of bad code, it’s good practice to label it with a TODO or HACK if you’re not going to fix it right away. For any code that has an external reason that isn’t immediately apparent, label it with that reason with preferably a URL explaining the workaround.

    Assume the person reading your code knows how to read code and understand most of the why’s behind it. Any comment needs to add more than reading the code carefully would. Any code that has no comment will be mercilessly refactored by all the people on my team.

    Examples of good comments:
    “// Required validation by standard FIPS-42 http://somewebsiteaboutfips42.org
    “// Hack, required by bug #239847 reported at http://connect.microsoft.com/…”
    “// TODO: this code is ugly and unreadable. Please refactor.”

  • Peter Bindels

    Any comment you type should tell you the reason why the code is the way it is and why it should or should not be changed to something else. In the case of bad code, it’s good practice to label it with a TODO or HACK if you’re not going to fix it right away. For any code that has an external reason that isn’t immediately apparent, label it with that reason with preferably a URL explaining the workaround.

    Assume the person reading your code knows how to read code and understand most of the why’s behind it. Any comment needs to add more than reading the code carefully would. Any code that has no comment will be mercilessly refactored by all the people on my team.

    Examples of good comments:
    “// Required validation by standard FIPS-42 http://somewebsiteaboutfips42.org
    “// Hack, required by bug #239847 reported at http://connect.microsoft.com/…”
    “// TODO: this code is ugly and unreadable. Please refactor.”

  • mcollins

    Would you agree that your example demonstrates that in this case a really long function name that adds no other value to the code is a really poor substitute for the well written and much clearer comment in the original code?

    I have never used or liked comments as a verbose and frequently incorrect description of what a piece of code does, but I appreciate the comments left by other good developers with reasons why and warnings about potential issues that wouldn’t otherwise be known to the person reading the code.

  • mcollins

    Would you agree that your example demonstrates that in this case a really long function name that adds no other value to the code is a really poor substitute for the well written and much clearer comment in the original code?

    I have never used or liked comments as a verbose and frequently incorrect description of what a piece of code does, but I appreciate the comments left by other good developers with reasons why and warnings about potential issues that wouldn’t otherwise be known to the person reading the code.

  • http://www.davearonson.com/ Dave Aronson

    Hence the whole idea of “smells”. It’s not necessarily evil, but warrants a closer look.

    Re making code slower: any decent compiler should optimize out the call.

  • http://www.davearonson.com/ Dave Aronson

    Hence the whole idea of “smells”. It’s not necessarily evil, but warrants a closer look.

    Re making code slower: any decent compiler should optimize out the call.

  • Sander

    When your code does something that’s not readily obvious, even an intention revealing method name may not be enough.
    Is it always possible to convey intent in a single phrase?

    In this particular case, I personally prefer the commented version to the refactored version, because I think the hack deserves an explanation.

  • Sander

    When your code does something that’s not readily obvious, even an intention revealing method name may not be enough.
    Is it always possible to convey intent in a single phrase?

    In this particular case, I personally prefer the commented version to the refactored version, because I think the hack deserves an explanation.

  • http://drawohara.com/ ara.t.howard

    i have a quite similar view. i ‘commented’ a bit of code recently thusly: http://drawohara.com/post/170183294/ruby-to-comment

  • http://drawohara.com/ ara.t.howard

    i have a quite similar view. i ‘commented’ a bit of code recently thusly: http://drawohara.com/post/170183294/ruby-to-comment

  • Chaitanya Gupta

    Wouldn’t it be better if your function handled the entire rendering code instead of just wrapping over `view.resize()`?

    function reRenderDynamicallyGeneratedWidgets_dojoHack(view){
    // Link describing this bug and the workaround.
    view.show();
    view.resize();
    }

    • http://blogs.agilefaqs.com Naresh Jain

      Good point Chaitanya. This works as well.


    Licensed under
Creative Commons License