9

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.

Juuso Hietalahti

9 Comments

  1. “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

  2. 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”.

  3. “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.

  4. 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 :)

  5. 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.

  6. 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…

  7. comments in code are _almost_ universally bad. properly written code comments itself!

  8. 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.

Leave a Reply

Your email address will not be published. Required fields are marked *

Pro-Human Quiz: