Who Are Those Comments For?

Scratch Notes

This isn't a post yet. It's currently just a collection scratch bullet points prepping the eventual post. Feel free to dig in if you're interested in the raw material.

I mention a post that I had with just one line of comments on it. I've since updated it to have a bunch more like what I'm now thinking. It's this page

The Notes

  • I'm sure this is well trodden ground, but it's the first time I've put this much focused, direct thought into it.

  • Cheryl A posted this on mastodon talking about comments how intuitive code is

  • I was going to send this page as an example of where I had only one comment to explain why a regex was there (by the time you see the page, it may have been updated to include more comments but at press time there was only one comment in the Usage section above the RegEx

  • As I scanned the code, I realized that the only reason I could get through it so fast is because I wrote it a few days ago.

  • I also realized I structure my code samples the same way every time, so that context is already in my head for free.

  • Hit me like a slap in the face that I was doing my readers a disservice. The folks who hit that page would have to parse out context completely for themselves with just the code and that one comment.

  • I put a lot of work into making my examples as concise as possible to make them as easy to understand as possible.

  • I use full code blocks two because posts/tutorials/whatever that scatter examples all throughout a post and require you to puzzle out what goes where are endlessly frustrating to me.

  • I also don't like examples that are scattered with comments so much that it approaches one line of comment per line of code. That requires context switching between thinking in code and thinking in spoken language that is both draining to me and terms of energy and detrimental in terms of my ability to understand.

  • All that got me thinking about the audiences for comments

  • Writing to a specific audience is something I think about with my prose and it's something I think about in my code (e.g. using descriptive variable names so future me can get my head around the code as easily as possible)

  • I realized there are multiple audiences and comments should be adjusted to the audience. Some of them are: - Me, as a single developer working on a snippet in my grimoire - Me working on a team of other developer on the same project - New developers who might come into that project and the relative complexity of the project - folks reading a post I made explaining or providing a demo of something

  • That's when it hit me. I've never defined who I'm writing the comments for. Without that, I'm just pulling some random recommendation or habit for the way I write them.

  • There's the "Five Ws" thing of "Who, What, When, Where, Why" which is some raw material, but the order really should be: Who, Why, What. (When and Where don't really come into play for the main use case)

  • I'm thinking we start with "Who" which doesn't produce any output. It sets the parameters for what we write for the rest of comments.

  • The first level of writing is the code itself. The "Who" has bearing on this. For example, if you're making a demo of a specific feature of CSS, don't throw in thirty lines of javascript that make the page look flashier. My rule of thumb here is: if a line of code can be removed and the example still works, remove it.

  • But the idea here is that "Who" you're writing for determines how much "why" and how much "what" you fill out.

  • As a reference, I put in that single comment in the code example. I had other comments in that I wrote while getting the code setup, but that was transient stuff. (Oh, shit, that's another category: transient comments. Never though explicitly about that either. But it makes sense. Just comment shit kinda all over the place, but then as you review and refine and refactor keep editing and cutting out what you can.

  • The "What" would ideally be self documenting in the code. It's probably a code smell if you have to do to much commending about "What" unless the what is really complicated (which in itself, is a code smell to investigate to see about simplification)

  • But that's "What" and the detail level. "What" at a higher level make sense for lots of audiences. I mean, at the highest level, you probably what to know what the code is supposed to do.

  • Maybe it's like introductions to chapters in a book, but in educational style of "tell 'em what you're gonna tell 'em"

  • As an aside, I'm thinking now about using "detail/summary" tags or something like that so that comments can be hidden in code snippets (or at least details can) but then expanded to see more for folks who want extra explanation.

  • There's the line I've heard "as much as you need, but as little as you can get away with". I prefer to reverse that to focus on refining down as much as possible: "as little as you can get away with. as much as you need".

  • And there's different levels of reading. Like, lots of times when I'm looking for something I want to just just the three lines of code to make it happen. I don't need context. I've got enough context already. But folks who are newer would need more. This is why I've started putting TL;DR at the top.

  • Actually "What" does come before why. But that's at the top level. It's the "What" of the entire thing. Like, what is the code for.

  • Okay, I take back the earlier stuff about the "What" it does make sense, but it's all about the resolution. Like, maybe the guideline is you define the "What" of a function or method.

  • Typing could help reduce the burden of some documentation, but that's more at the what level.

  • Make a distinction between where comments are in terms of one of three places: outside the code, in the code as a block above a function, directly above or beside the line of code it's referencing.

  • As I'm messing with this, I really don't like most inline comments for general explinations, I do like the idea of showing a block of code and then going throught it line by line after.

Temporary Conclusion

  • First, decide your audience by answer the question "Who". And pick only 1. Don't try to write the same thing for multiple audiences. You'll frustrate them everybody involved.

  • Defining "Who" sets the guidelines for "Why" and "What"

  • There should top level "What" that says what the code does

  • There should also be "What" for each block of code (where block has a variable definition but would usually be around the function/method level.

  • "Why" is used for the tricky stuff. When you squint at it and it's non-obvious at a glance that's when Why comes into play. Given that there's a context switch that has to happen when moving from spoken language to code maybe there's a rule of thumb like, if it takes you more than 10 seconds to figure out why a line of code is there you add a "Why" comment if it's for code you know and understand. But, if you're writing code for a tutorial (so your "Who" is folks that are new to it, that changes.

  • And the tutorial audience is not always the same either. If you're writing a tutorial for ruby, or javascript, or python for folks who have experience in one of the other two you don't need to add as much detail as if you are covering list which is significantly different.