Don’t comment your code

August 20, 2009 by nuno costa 8 comments Stumble It del.icio.us

comments

I’ve seen a lot of “beginners best practices” advising to comment your code to exhaustion. To comment every single line of it, so in the future you know what you where doing!

That’s plain wrong!

Your code should be simple, very simple. In fact if you can’t understand your code, you should refractor it to a simple form!

 

The truth is if you have to comment your code so you will understand it in the future maybe this should not be your profession!

 

You as a developer should be able to write simple and clear code, you should be able to communicate with fellow developers throw your code.

 

Just imagine you are talking with some one and he has to explain you every sentence! This is what you are doing by over commenting your code!

 

By all means comment your code, but do not comment explaining what you are doing, instead write simple code and explain the general purpose of that code block!

 

8 comments so far Add Your Comment

  1. by triton on August 20 2009 at 18:17

    This is very true.

    As you greatly put it: “explain the general purpose of that code block!”.

  2. by Ricardo Amaral on August 21 2009 at 02:27

    Let me start by saying that I don’t agree, at all, with you :)

    “The truth is if you have to comment your code so you will understand it in the future (…)”
    The comments are not there for you to “understand them in the future”, the comments are there for you to know what the code is supposed to do in case you forget.

    “You as a developer should be able to write simple and clear code, you should be able to communicate with fellow developers throw your code.”
    Just because someone comments their code doesn’t mean their code is complicated and unclear. Most people can read my code, I try to make it clear as possible (that’s why I rewrite a lot of stuff), still, I comment my code a lot. But that’s just how I am. I like to keep things tidy and explain what I’m doing for me when I get back to that code in the future and can’t remember what I wrote or for someone else that happens to have my code (open-source stuff).

    “Just imagine you are talking with some one and he has to explain you every sentence! This is what you are doing by over commenting your code!”
    I’m sorry but that’s a stupid analogy. If you are talking to somebody and he doesn’t get anything you say, maybe the subject is not of much interest to that person but assuming it is, maybe that person is just plain dumb. If you were thinking out loud and typing your code development with someone next to you, they would probably follow you just fine (as in talking to someone and that someone understands you). But if you just give some piece of code to someone, it will be much easier to understand the code if it’s commented than comment that is not. It doesn’t matter if you’re smart or write clear code, you’re the one who wrote it, you’re the one who knows the code like the back of his hand, not the person who you gave the code to. That person will need to review it and understand it and that, is so much easier if the code is properly commented.

    The way I see it, you’re just being lazy. But hey, to each its own.

  3. by nuno costa on August 21 2009 at 03:35

    Hi Ricardo,

     

    It’s not about being lazy, It’s about being clear, although I consider laziness to be a good quality for a developer but that is a subject to another discussion.

     

    I tried to sum it up on the last paragraph, I like comments, and think they are important, I’m just against excessive comments.

    A comment should be a guide, a hint, to what that peace of code does, not step by step intructions.

     

    Let me give you an example of what I thinks is ok and what’s not.

     

    /*
 
*  This function retrieves the comments for a given post
 
* @param postId integer
 
* @returns: collection of posts
 
*/
 
function getComments($postId){
 
    <some code>
 
    //some important note about the following code
 
    <more code>
 
}

    to me this acceptable and desired!

     

    function getComments($postId){
 
   //connecting to db server
 
   mysql_connect()
 
   //selecting database
 
   mysql_select_db()
 
   //preparing sql
 
   $sql=…
 
   //execute sql statment
 
   mysql_query()
 
   //looping trough records and get something
 
   while(){
 
 
 
    }
 
}

     

    Can you see the difference ?

    If you where to maintain an application how would you like to have the code ?

     

    You should comment only when it’s meaningful otherwise you are just making your code dirty and hard to follow

    By the way, I really like your email address :P

  4. by Brant Peery on September 16 2009 at 17:58

    I agree with nuno costa on this. With that said though, there are way to many ‘programmers’ out there that under comment their code. The biggest problem with that is that they are also sloppy programmers. They rarely follow any best practices and the methodology is a bit out of the ordinary. So it becomes very hard to follow the code in your mind. I have even encountered situations where the hackjob doesn’t even match what the developer intended. It just kinda worked somehow and so they stopped hacking at it. This would be an excellent example of a place where commenting the intentions of what the developer was trying to accomplish with each line or set of lines would be helpful.
    But if a developer can follow best practices and said developer uses common methods of accomplishing things then he shouldn’t need to comment what just about any beginner to average developer in that same language would understand about that line of code. That becomes redundant and wasteful. Unless of course he expects beginners to read or maintain the code. Then comments will be used to teach. But that is not normally the case.
    I do believe that if code is used that is out of the ordinary or more advanced than the average programmer that might look at that code (even if it is the developer himself) then the more comments the merrier. I have often looked back at code that I implemented and been grateful that I didn’t have to do the research again. Sometimes it really helps to have included such good notes (comments) in my code.

  5. by Crazy12 on October 11 2009 at 03:45

    This means that traffic is backed way the hell up. ,

  6. by m4niac on October 9 2010 at 07:22

    makes perfect sense to me :) totally agree. thanx

  7. by Pete on September 13 2011 at 13:04

    Comments are basically a way of the developer saying i can’t describe what this function does with a simple name so i’m gonna have to document the intricacies for my future self just in case i forget.

    The solution for this type of problem was created many years ago

    “Make each program do one thing well. To do a new job, build afresh rather than complicate old programs by adding new features.”
    - Doug McIlroy

    Split the problem to the point until it becomes self-documenting.

  8. by Pete on September 23 2011 at 01:18

    The problem isn’t you coming back to your own code. You comment for the poor sap that has to modify your code 2 or 3 years from now and you are long since gone and if you dont think this is important, you haven’t been burned by the egotistical SOB who thinks his code is so perfect and elegant that it is self documenting and adding a comment would detract from its beauty. Like most things from a narcissist, it’s only beautiful to them and to the rest of the world its sphagetti code.

    I fire programmers who don’t document the module, the function, its parameters and return values and every decision point.

Your Comment

More from francodacosta.com

© francodacosta.com - All rights reserved