Two years back, someone asked me to review some Inform 7 code and make some bugfixes. I opened the source in question, updated it to the latest version of Inform, cracked my knuckles, and loaded up the bug list.
I read the first bug.
I stared at the source code.
I looked at the bug again.
I looked back at the source.
Then I said a few choice phrases in the kind of language I don’t use in front of my father. Because no matter how readable the code was, I had no idea what was causing this bug or how to go about safely fixing it.
I wouldn’t be so hard on the coder, except that she was me.
Why I didn’t comment (and why I should have)
When Caelyn and I were writing One Eye Open, I didn’t comment my code. At all. Inform 7 looked like English, so I figured I didn’t need to. Besides, no one was ever going to look at it except me and Caelyn, and I was the primary coder.
When you’re in the thick of a project, you understand how everything fits together, and it’s even better if you’re coding solo. You know the design, large scale and small, and you understand the logic driving that design. In essence, the code is commented – but for you, and only you. The comments are living in your head, and if you’re the only one working on it, then you don’t need to explain your code to anyone else.
But Future You might have an opinion or two about that decision. Future Me certainly did.
My code specialty is kludging. If all I have is a hammer, then I can use it as a screwdriver, a lever, a s’more stick, a ruler, a bottle opener, a panini press, or whatever else the job calls for, and I’ll get the project done… somehow. But my hammer-centric results aren’t as pretty as the results of using the proper tools.
Caelyn and I released One Eye Open in 2010. I’d worked with Inform 7 before, but OEO was my first full game, so I was still learning how the language works. I wouldn’t say the whole game is a kludge, but… I’m not going to pass around the source code, either.
On a line-by-line basis, it’s easy enough to read the OEO source. But figuring out how it all fits together… or why I made some of the decisions I made… that’s another matter entirely. And if I don’t understand my code well enough to see why I thought something was a good idea, then a well-intentioned fix might introduce more bugs than it resolves.
I have a lot more tools in my toolbox now, and my s’mores are much prettier for it. But the OEO comments that used to live in my head are long gone, and the way I write I7 code in 2015 is not the way I wrote it in 2010. If I’d commented my code in the first place, the OEO fix process would be a lot faster and a lot less painful.
Many people (such as Jeff Atwood) have opined that sufficiently well-written code should not need comments, as the first goal should be to optimize the readability of code. I do not disagree with this goal, but I find that it’s tricky to judge the clarity of my own code. Having burned myself in the past, I would rather overcomment than undercomment.
Design summaries – how puzzles and areas were set up.
It’s surprisingly easy to forget a puzzle solution, especially when multiple steps are involved.
Complex activities and rulebook changes – what the purpose of the code is.
It may be easy to see what the code does without understanding why it was necessary or desirable. For example, the current build of “Rainbows and Dance Parties!” includes extensive alterations to how player commands are processed. These changes are bugfixes to resolve disambiguation problems, but it’s not necessarily obvious from the code why the command to go inside should always be rejected and replaced with “fly to Indiana”.
Extension hooks – how other people should use the code.
The most widely distributed pieces of Inform 7 source are extensions (Inform 7 libraries, essentially). If you’re writing a piece of code for other people, then it’s important to document how they should use the code, with particular notice to whatever variables, activities, kinds, etc. are important for an outside user.
Future plans – things that need to be added or changed.
If I leave these notes in a notebook, I’m going to forget about them. If I put a big splashy ***CONTINUE note in a comment, there’s no way I’ll forget. (“Todo” is more traditional, but mine are easier to spot at a glance.)
Potentially useful comments
Architecture notes – how the code is organized.
My source structure varies significantly by project. The headers (book, part, chapter, etc) are helpful for navigating, but if I have any doubts about whether related code is easy to find, then I include a comment about where to find related code. (For example, if NPCs are grouped together separately from rooms, then I’ll include a comment near each occupied room about which NPCs are in it.)
Code summary – what the code actually does, high level.
Inform 7 looks like English, so it’s not unreasonable to expect the code to be fairly readable. But it has a whole lot of internal jargon, and not everyone has inhaled the entire manual. (What’s the difference between an action, an activity, a rule, and a rulebook?) If I’m doing something in an unusual way (linking rooms via a table of room exits, for example) then I often include a quick summary of how the code works.
Sporadically useful comments
Code explanation – what the code actually does, low level.
Asserting that this can be useful is a somewhat controversial position. Many new coders hear that commenting their code is important, but they’re not entirely sure what comments to make, so they write their code twice (once in code, once in the comments). This is rarely a good use of time, and it’s obnoxious to anyone else reading the code.
But when you’re still learning a language, it can be tricky to understand just what the code is doing, and it’s better to have overly commented code that you understand than uncommented code that bewilders you. In that case, leaving comments can ensure that your comprehension level stays high. For example, my understanding of Inform 6 is quite terrible, so I comment all my I6 inclusions in detail to save myself from confusion later.
TL:DR; As a best practice, comment your code
If you’re working alone, then you don’t have to comment your code. No one will complain if you don’t. It will save you time in the short run. Your files will be more concise.
But by commenting your code, you can crystallize your understanding of the project and pass it along to everyone else who reads it, which can be the difference between a three-line change and a painful slog through your entire code base.
Future collaborators will appreciate it, even (especially!) if they’re you.
Thank you to everyone supporting Sibyl Moon through Patreon!
If this post was useful or interesting, please consider becoming a patron.