4 ms·
Code comments must be a balancing act because they are not free. Documentation for its own sake is not an unalloyed good if the value does not justify the cost.
by jandrewrogers 8y ago
Code comments must be a balancing act because they are not free. Documentation for its own sake is not an unalloyed good if the value does not justify the cost. You are fighting entropy here, so maximizing documentation value generated for minimum programmer effort is important.
Code should mostly be self-documenting in terms of the "how", and coding style, idioms, and guidelines should be enforced to ensure that the code actually achieves this goal. Importantly, a lot of implicit intent by the programmer can be made explicit through coding style alone. I prefer this method when possible because inferring programmer intent is one of the single biggest headaches for legacy code, and when intent is made explicit by the code itself you don't have to worry about the documentation diverging from the code nearly as much. I say "mostly self-documenting" because there are occasional cases where the "how" is not obvious even if the code is e.g. a specific result is guaranteed as a side effect of non-local state.
The "why", on the other hand needs significant documentation to exist inline with the code, and you typically need two types of "why"s. First, for some things you need to explain why a specific implementation was chosen versus other possible implementations. Sometimes an implementation is arbitrary -- and I document this too, so people know it can be swapped out with minimal consequence -- but other times it was chosen to effect specific optimizations based on specific assumptions, both of which need to be documented so that a programmer can determine if the assumptions are still true. The other type of "why" is, of course, why does a specific bit of code need to exist at all? I've seen extremely innocuous code that fixed a subtle bug or edge case that would almost certainly be refactored away by a programmer some day if it wasn't explicitly documented that a tiny bit of logic was doing something very important.
From an "80/20 Rule" perspective, I find that code styles the explicitly capture programmer intent, plus some well-written inline "why" documentation does most of the heavy lifting for code maintenance while minimizing the volume of documentation that has to be written and maintained by the programmers separate from code. There should also be some high-level documentation on design assumptions and scope, but programmers are less involved in that on a day to day basis.
- chrisweekly 8y agoIME (20 years in web-related software dev / arch / mgmt), the best ROI in this area comes from two things: - good commit messages - references to persistent requirements artifacts (eg Trello cards, Jira tickets, whatever) YMMV... but really doing these two things makes a huge difference.
- thaumaturgy 8y agoBoth of your examples require the developer to access some resource outside of the code itself in order to understand what the code is doing (or why it is doing it). So those things are both good also, but I consider them to be a fallback for cases where the code isn't commented like it should be.
- chrisweekly 8y agoComments can provide context by simply providing a link like "See Issue/ticket/card ID #123". That plus git blame, good commit messages, and feature branches named for the same ID, makes for a coherent whole -- without adding much overhead in terms of comment writing and maintenance.
- BonesJustice 8y agoWell said. Particularly in highly optimized code, it can save future maintainers (e.g., you) precious time if you take a moment to explain the things that are not obvious and could, at first blush, look like bugs. Writing good comments requires a lot of vigilance: not only do you need to know which decisions to explain, but good documentation often entails explaining why you didn’t do something. “We don’t need a memory barrier here because ____.” “There is a subtle race between X and Y here, but it’s benign because ____.” Of course, if your colleagues are not as disciplined as you, even the best comments can fall victim to comment rot over time.