How Not to Comment Your Game Code

I was changing my existing network code, and was examining a piece of code that was looping through all the character objects. In that loop there was a section that started like this:

; loop again
For …

“loop again?”

I had a comment that said “loop again”. I wonder what the heck I was thinking when I was writing that. It certainly ain’t helping anybody to write such comment. It’s pretty obvious that ‘for’ begins a loop, so there’s not much point writing “loop again” there. If I saw the need to comment something, then why not write something that could actually have a meaningful purpose?

Oh well. We live and learn.

9 thoughts on “How Not to Comment Your Game Code

  1. Alfred R. Baudisch

    “I don’t write much comments. My goal is that the code speaks for it self. But it is funny to find 3-4 year old code sometimes and with no comments. It takes a few minutes (hours) to figure stuff out :)”

    But THAT is the point. You can spend 5-15 minutes writing comments while coding, and saving hours/days later (depending on amount of code).

    :P

    Reply
  2. Alfred R. Baudisch

    I love to comment. For each function/class/important lock, after I finish, I write a long and descriptive documentation in JavaDoc syntax.

    I can still use 10 years old code without even bothering “what the heck does this do, I cant remember”.

    Reply
  3. desertdweller

    “I don’t write much comments. My goal is that the code speaks for it self. But it is funny to find 3-4 year old code sometimes and with no comments. It takes a few minutes (hours) to figure stuff out :)”

    Exactly. Every once in a while, I dare to look back at some of my code, and I’m horrified that I have no idea what some parts are there for.

    Reply
  4. Toni Mäkinen

    I don’t write much comments. My goal is that the code speaks for it self. But it is funny to find 3-4 year old code sometimes and with no comments. It takes a few minutes (hours) to figure stuff out :)

    Reply
  5. Jake Birkett

    Luckily because I sell my framework I feel I have to make good comments because other people will be reading them, so it’s like having someone look over my shoulder.

    Reply
  6. Juuso Hietalahti Post author

    sean, I do agree. one should seek to avoid comments… and rather name methods/functions/variables/etc. in such way that the ‘logic reveals’ itself.

    sometimes it might be a good idea to provide little insight why/how certain stuff happens…

    Reply
  7. Eli

    I swear; I write the most horrid comments in the whole world. The only plus; is that I can continue to understand them. Watch out; however, if you be the unfortunate person who has to read or work with my code. I am working on it though. So.. yes, onward and upward.

    Reply

Leave a Reply

Your email address will not be published.

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>

Pro-Human Quiz: