Saturday 3 December 2011

QQQ

In his talk at Quakecon this year, legendary programmer John Carmack (Keen, Wolfenstein, Doom, Quake, Rage) talked about code quality, and how even the very best programmers make lots of mistakes. So he says that every programmer should think about ways and methods that make mistakes happen less. This is something that I totally agree with, and this kind of thinking is the basis of the coding standard and methodology that we use at Ronimo Games.

One of the nicer things that have crept into our coding standard over the years is a tiny little trick that keeps a lot of issues from happening. It is pretty obvious, but I know a lot of programmers who don't do something like this, so I figured it would be useful to mention this one today. :)

Often when you are programming something, you quickly make some changes somewhere else to test one specific situation. For example, maybe you are testing the graphics of a weapon against a specific enemy. If that enemy dies all the time, you need to find another one to test on, so a quick change could be to decrease the damage of that weapon against that specific enemy by 90%. Now the enemy stays around a lot longer and you can test more efficiently.

However, once you are done working on that weapon, it is really easy to forget to remove your little hack. Later someone else spends hours searching through code why that enemy dies so slowly. Only to discover that forgotten hack of yours.

Many coders would say now that this is sloppy programming and you should just be a better programmer and remember these things. However, while programming, there are so many things to consider that it is easy to forget one once in a while, no matter how good you are. It is better to design your working method around the idea that you do make mistakes, then to simply say you should be a better programmer.

Now since these little hacks are a great help when programming, everyone I know uses them a lot. So I came up with a really simple trick to keep track of them. Whenever you do a little hack like that, you add a comment with the text "QQQ". So like this:

if (enemy->getName() == "UrQuan") damage *= 0.1f; //QQQ

All coders at Ronimo do this ('voluntarily'). Before we commit our newly written code to the source server, we search for QQQ to see whether we forgot anything. That gives us a list of all the temporary hacks that are still in there. And because we all use QQQ, and not something different for each programmer, we can quickly find QQQs that someone else forgot to remove.

Since QQQ is basically just a marker to remember something, I also use it when I realise I need to remember to rework or check something later on.

So why the letters "QQQ"? This specific term has the benefit that it never occurs in any normal sentence, and is short enough to quickly put in while working. I actually stole it from my brother and sister, who are both researchers and put it in their texts when they need to fill something in later.

11 comments:

  1. Neat little idea. I always go through all the code diffs at commit time so I haven't had much need for that yet, but it could help spot the occasional slip.

    ReplyDelete
  2. I assume you added //QQQ to VisualStudio or do you have a commit-hook running on your versioncontrol server?

    My trick is the same as Anonymous, do a diff before committing. Also whenever I am bughunting or testing some stuff and I have added some temp code, I always use CTRL+Z to make sure I don't forget some lines.

    ReplyDelete
  3. QQQ is just a comment I type in code.

    Checking what you commit is definitely also a good thing to do. It doesn't function as a reminder for things you need to check later on, though, and it requires a bit more discipline, but ideally, I try to do both checking the diff and QQQ. :)

    ReplyDelete
  4. Nice post :)

    I personally use // TODO (OJ) when adding something temporarily. Before each submit, I always do a global search on that tag to see whether I've missed something. And, as Anonymous remarked, I always check my diffs when submitting something, which in my opinion is something every programmer worth his or her salt should do anyway.

    If something needs to persist across submits (e.g. a hack for a specific deadline or whatnot) I use the variant // HACK (OJ). Everyone can easily search for HACK, and the initials point you to the programmer responsible.

    I would recommend always adding a short description to QQQ, HACK, TODO or whatever standard you're using though. I've come across hacks introduced over two years ago. Are they safe to remove? Why are they even there? Are they still relevant? Without a description I wouldn't know what the original programmer intended, and the original programmer might have forgotten or might not even work at the company any more. A small clue (e.g. "reduced all damage by 20% for E3 demo") would help a lot imho :)

    ReplyDelete
  5. I think the TODO and HACK seems to be widely regarded as standard, though QQQ is fine. I still use it in my code as i continued keeping the coding standards of ronimo games :). In VS2010 there are even functions built in that can search for it and do nifty stuff with. I am uncertain about the exact functionality but ive seen it once while checking out the new features that come with vs2010.

    regards,
    bk

    ReplyDelete
  6. In LaTeX I have a \todo{} command that prints its argument in the margin, easily spotted when proofreading. It is also easily greppable in the source like //QQQ.

    ReplyDelete
  7. ehhhh i think www.proun-game.com got hacked might wanna check it out D:

    ReplyDelete
  8. Hmm, 1-bit Ninja isn't the game I was thinking of, but it looks great as well! :)

    ReplyDelete
  9. Useful tips! If using QQQ, TODO, or whatever, there is a feature in visual studio to treat these terms in a comment as a warning.

    for vs2008:
    visual studio > tools > options > environment > task list

    anything listed in "tokens", when in a comment, creates a warning when building, and lists in the errors list. Useful for keeping track!

    ReplyDelete
  10. I was just about to say that ^^^

    To add to that; you can view all the tokens (//TODO //HACK //MY_TOKEN etc) in the Task List (CTRL+W , CTRL+T) This is probably faster and easier then doing a CTRL+F(ind) in the project.

    ReplyDelete
  11. @todo and regression tests via unit tests here for webdevelopment.

    ReplyDelete