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.


    Licensed under
Creative Commons License