Cleaning the Code

As UncleBob discuss on his article Commented out code is an abomination, leaving codes commented out does not help the other developers to understand/write the code better, but only create problems. I will keep the same example he gives, for clarity and assuming everyone saw at least one piece of code similar [no, no I know you did not do]. Here is the example he gives:

protected void log(String message, int priority) {
      if (project != null) {
        project.log(message, priority);
      }
//      else {
//        System.out.println(msg);
//      }

    }

First of all, it breaks the rule of xp, “don’t code for future.”  Probably the developer was thinking writing to console will be a requirement in future, and wanted to help other developers going to use his code.
The code should be as simple as required, just doing what it should do. Adding extra complexity will create lots of questions.

Secondly, if he really wanted to leave a comment, it should not be a commented line, but a comment to the top of this functionality, telling what it is in his mind : “This if may have else statement writing the code to the console.”

Thirdly, and worst case: breaking another rule for defensive coding: he could left it for himself….
It was a requirement, but he couldn’t write/compile it as he wanted. Maybe he wanted to write a xml file, but could not [did not have time…], and left this commented part as a reminder [believing without comment he will remember…].
And maybe because it was not mandatory, he delivered without an else…
Obviusly, he may want to add optional else part with a functional code later [if he can]…
Then, I reckon, he should add TODO: keyword to the start of his comment:  
“TODO: This if should have an else statement writing the message to xml file”
Lastly, it was an important piece of code [lots of lines…], and he wanted to keep it to use later since he was not confident to write the same again himself. I could offer to have that piece of code locally and  write a reference as a comment.
Then he can argue that “I want it in source control so that I won’t lose it!”
I would not mind creating a commented lines file, and extract this piece of commented lines as a method and referencing the method name here.

All in all, I can’t see a point in commented lines to stay there…
It should not be the new developer looking at code, and deleting old codes [requires some courage since she may lack some knowledge] , but the owner of the code should really be responsible for his code…

C# is quite handy in terms of writing comments and creating documents from code. In the next blog, I will show some nice examples. Writing solid codes should not be that far away…

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s