Write Notes for Your Code

New Essay

Decision Table Patterns: How to write better decision tables and fix common issues. If you've wanted to try formal methods but weren't sure where to start, give decision tables a try! You can learn all the theory in about five minutes and immediately start using them in your code.

Write Notes For Your Code

"Should you comment your code" has, once again, started fights all over The Online. I love how this has become one of the most controversial things in programming. Everybody has a strong opinion, there's no commonly accepted "right answer", and people can agree on 99% of software but still fight over whether they should be commenting their code.

I come down hard on the "comment your code" side. I don't think self-documenting code and tests and types and stuff are enough to replace most of the value of comments. But that's a longer essay for the blog. Instead I want to talk about something I noticed that I think everybody could agree would be useful, regardless of what side of comments you're on.

So the big argument against comments is that they fall out of date and can be misleading. This is reader-centric: that you're trying to understand code that someone else has written. You're working on a team and the comment is trying to communicate between the writer and you. Or it's familiar code that's been changed by someone else. The big argument for comments is that code cannot expressively convey a lot of important meta-information. It's writer-centric: it's about the responsibilities you have as the writer of the comment for people unfamiliar with the code.

So what happens if you're both the reader and the writer of the comment? You can express information that the code cannot convey, so comments help, and it's code that you're both familiar with and understand, so you're not likely to be misled.

def request_application_info(params):
  # http call happens in VendorClient to 
  # '/request/:id/?status=pending'
  some_setup()
  more_setup()
  foo() # <- effect callstack continues here
  teardown()
  more_teardown()

We can use our own notations and adapt the comments to exactly the things we need. This is especially valuable when working on the same codebase for a long time, as we progressively build up more and more clarifying comments that help us orient ourselves.

The downside of writing comments for ourselves is that they clutter up the code for all of our teammates. Since the comments are not written for them, it's unlikely that the comments will be useful. The comments are just misleading noise. In an ideal world we have projectional editing and this would be moot, but this is not an ideal world.¹ We could instead write the notes in a different file with references back to the relevant code they apply to:

foo.py::request_application_info: 
  This makes an http call via callstack

request_application_info -> foo -> bar 
  -> baz -> VendorClient.send(id, "pending")

http call is '/request/:id/?status=pending'

Hey wait, isn't this just taking notes?!

I was shocked to realize that I've never seen anyone do this. None my coworkers, none of my friends, none of the people I read online. The most I've ever seen was a coworker who would write down transient notes in a physical notebook. But they weren't permanent notes for later reference. If they took notes about a module while fixing a bug and three weeks later had to come back to that same module to fix different bug then they would start from square one. Nobody I know takes permanent notes about code they're working on. Then again, it's not like I'm any better. I mean, I hadn't even thought of this until I saw some comment flame wars and geared up to wade in.

I don't think this completely solves the comments debate, and I still think there's a lot of value in writing comments (moreso than most people), but it seems like a technique that would appeal to people on both sides of the issue.

If you're reading this on the web, you can subscribe here. Updates are once a week. My main website is here.

My new book, Logic for Programmers, is now in early access! Get it here.