3 ms·
> Comments should be reserved for the rare bits of code that are influenced by factors beyond the code itself (for example, a customer requirement or a bit of h
by rkangel 10y ago
> Comments should be reserved for the rare bits of code that are influenced by factors beyond the code itself (for example, a customer requirement or a bit of historical context)
This statement may be true in language domains the author is used to, but is certainly not true across the full spectrum. Also - there are two sorts of comments: 'what' comments, and 'why' comments.
'What' comments tell you what the code is doing. A lot of the time, in a lot of languages, if you code clearly these are needed only rarely, if at all. They are telling you what the code is doing, mostly as a convenience - they can always be replaced by spending time reading the code to see what it's doing. There are a number of situations where they are useful though, mostly obviously in languages like C or even Assembly where code often cannot be made easily readable. The 'what' comments allow you to quickly parse code to build up understanding of what's going on. Good assembly has a very high comment to code ratio - you are mostly reading the comments rather than the code to grok it. Occasional 'what' comments on a bit of C pointer arithmetic allow you to understand the authors intention and check against that 'specification'. I agree that in more expressive languages, these sort of comments become rarer and rarer.
'Why' comments are irreplacable in every language, and are what the author seems to be referring to in the above quote. "I have chosen to do this like this here because...". Because otherwise X unforseen bug, because otherwise Y performance issue, because Z client requirement. However expressive your code, that extra context is never going to be communicated by the code itself.
- charles-salvia 10y agoI agree with the comment about assembly of course, but ironically I find myself spending more time writing comments when programming in high level languages like Python, rather than in C. The reason most of the time seems to be that many high level scripting languages (like Python) are dynamically typed languages. So things like function definitions contain no information (other than the variable name) that explains what the inputs/arguments might actually be. I often find myself having to write comments to make it clear what the parameters are supposed to be so someone reading the code instantly understands what needs to be passed to the function, whereas in a language like C or C++ that has static typing, the type would make it obvious.
- chriswarbo 10y ago> I often find myself having to write comments to make it clear what the parameters are supposed to be so someone reading the code instantly understands what needs to be passed to the function, whereas in a language like C or C++ that has static typing, the type would make it obvious. I'd encourage turning these sorts of 'comments' into Javadoc-style 'annotations'; they're still comments, so language implementation will ignore them, but that small amount of structure makes it possible for separate tools to perform sanity checks (i.e. obvious combinations of incompatibly-annotated types), or even to show annotations at call sites in an IDE (e.g. when hovering over a name).
- abecedarius 10y agoI'd rather call that 'how' instead of 'what', because there are two things you might take "what does this code do?" to mean: its purpose or the way it works. A square-root function, for example, might have How: newton-raphson iteration, 2 rounds What: return a number within 1% of the positive square root of the input, which must be in a certain range Why: it's for a rendering, it doesn't need to be precise In this breakdown the 'what' is what I tend to want the most often, as a reader. It gives an anchor to check the code against, and enables reading that code without having to understand all the other code it calls on -- just the 'what' comments of the other code.
- AstralStorm 10y agoWhy is the more important one - it is the requirement. I'd rather see something like this: Why: We need to calculate distances between widgets to pack them so that it looks nice to the end user, but is also fast - start must not take longer than about 1 second. We are running on embedded hardware. What: Use square root approximation for distance defined over the range of pixels available on screen. How: Newton-raphson iteration, 2 rounds, fixed point.
- abecedarius 10y agoFair enough -- I mainly wanted to point out an important distinction blurred by "why vs. what". It's up to the context whether you'd care more about this kind of why or what. However, it's this what -- what the code is meant to do -- that's both the most basic info for maintenance and in poorer supply, as I've seen it. It's often easier to get an off-the-cuff answer to "why do that?" (or to not need it) than "exactly what was this code meant to do? Does the rest of the system depend on the fact that it freems the bleetches, or can I change that?" -- in that case you're more likely to get back "Hm, I'd better read all this related code to swap it into my head". Your experience might be different, and that'd be kind of interesting.