4 ms·
Early 30s here and I've realised that comments are worse than useless most of the time. Nothing enforces that the comment is correct, so a significant proportio
by lmm 7y ago
Early 30s here and I've realised that comments are worse than useless most of the time. Nothing enforces that the comment is correct, so a significant proportion of comments will be false, so no comments can be relied upon.
Descriptive types, clear tests, and sensible variable names are much more effective strategies for making code understandable. Comments should be a last-resort stopgap.
- ZeroMinx 7y ago> Comments should be a last-resort stopgap I'd add; Comments should be saying _why_ this crazy method is here. You can always parse the code to figure out what it does. In a few months/years (depending on your memory) you will not remember _why_ this code was put in place.
- dbingham 7y agoHonestly, I would add this whole comment to the list of "absolute truths" juniors unlearn as they get more experience. And I would also point to the original post's point that types of experience matter - just because you're early 30s doesn't necessary mean you've had the right experience. If you still believe this, then - to be brutally honest - I would question the quality of the teams you've worked with. Comments don't have to decay. Discipline is important. Culture is important. And yes, these have to be intentionally set and upheld. If you set a culture of discipline around maintaining the comments with the code, and ensuring they are updated, then it's really not that hard to do it. If the developer doesn't remember to do it when making changes, then the code reviewer can catch it and enforce it. And nothing really substitutes for an english language explanation of the "why" and the intention of a particular section of code. A good comment explaining why something was done a particular way, or what the code was intended to accomplish, can save hours of walking up and down call stacks. It's also something that cannot be communicated through unit tests, or even integration tests, a lot of the time. Those communicate the "what" and the "how" - not the "why".
- lmm 7y ago> If you still believe this, then - to be brutally honest - I would question the quality of the team's you've worked with. To be equally brutally honest: right back at you. I would trust the quality of those I've worked with over those who believe in comments, any day of the week. My point was simply that I started as a believer in comments when I was more junior, and became anti-comment through experience. So even if we believe senior people are more likely to be right than junior people (which I very much doubt, frankly), that tells us little about whether comments are good or not. > If you set a culture of discipline around maintaining the comments with the code, and ensuring they are updated, then it's really not that hard to do it. Human programmers have a limited discipline budget, and if you're spending it on keeping the comments up to date then you're not spending it on other things. Yes, you can use manual effort to keep code explanations up to date, just as you can use manual effort to ensure that you don't use memory after it's freed, or that your code is formatted consistently, or that the tests were run before a PR is merged. But you're better off automating those things and saving your manual effort for the things that can't be automated. > And nothing really substitutes for an english language explanation of the "why" and the intention of a particular section of code. Disagree; code can be much more precise and clear than English, that's its great advantage. As the saying goes, the code is for humans to understand, and only incidentally for the computer to execute. The whole point of coding declaratively is that the "why" is front and center and the "what"/"how" follows from that.
- mannykannot 7y ago> code can be much more precise and clear than English. [my emphasis.] As a common feature of most higher-level languages is that they co-opt natural language terms (and also mathematical notation, which is an option in commenting) with the intent to increase clarity, can you show us an example where code is more clear than natural language in explaining both what it is doing and why? If you are working in something like APL, I can see there might be a case... I am not so much interested in the precision issue, as both code and language can be very precisely wrong or right.
- gamblor956 7y agocode can be much more precise and clear than English Agreed, code is much more precise than English. But precision is not the same thing as being meaningful and without context, precision is useless. Code generally sucks at context, which is why every programming language worth its salt has comments.
- kelnos 7y ago> Comments don't have to decay. Discipline is important. Culture is important. And yes, these have to be intentionally set and upheld. These are things that are often completely outside your control. > If you set a culture... At most shops, you don't get to set the culture. About the only time you do is if you're a founder or early developer. Otherwise you have to fit into the existing culture, or attempt to find a company that better reflects what you want. Sure, it's not hopeless; you can likely influence to some extent, but your influence is usually limited. > And nothing really substitutes for an english language explanation of the "why" and the intention of a particular section of code. I do agree with this. Any code that can't be written in a self-documenting way absolutely must be commented. However, if you find the need to do this often, it might be a sign that you should focus more on code clarity and less on (likely premature) optimization, or perhaps consider if you're really using the right tool (language, framework, etc.) for the job at hand. I will admit that I probably comment less than I should, but I feel like the average is way too verbose, and that enough comments are out of date and incorrect (often in very subtle ways) that it adds significantly to my overhead when trying to understand someone else's (or even my own) code.
- kurtisc 7y ago>If the developer doesn't remember to do it when making changes, then the code reviewer can catch it and enforce it. They can. Just after correcting all the buffer overflows and before fixing all the use-after-frees. Then the comments can be consumed by all the other teams with the discipline and culture to avoid writing bugs for all time.
- kochthesecond 7y agoI'm 29 and can barely remember the code I wrote last week. Comments don't get updated when the requirements for the code change, more often than not end up as misleading. The only thing worth commenting are actual libraries that are maintained, and 'magic values'.
- chrshawkes 7y agoAll those comments of "blah blah blah gets or sets a value" on my class properties, why do we add all that overhead to our projects to the point we have to use tools like GhostDoc to write our worthless comments? This industry is on crack sometimes. I simply like comments for adding things like... so and so told me to do this... or simply documenting weird behavior or weird business logic.
- war1025 7y agoComments and `git log -p <file>` to see what the comment originally referred to is pretty useful. My personal favorite comment style is to wrap a chunk of code in `#{` `#}` blocks and add a general comment of what that chunk of code is accomplishing. Sort of like an inline method.
- mannykannot 7y agoNothing enforces that the code is correct, either, not even tests, as tests are also code, plus there is the utter infeasibility of exhaustive testing. It does not follow from the possibility for error that a "significant" proportion of comments will necessarily be false. In my experience, that is most likely when an organization has commenting as a mandatory part of its process, which inevitably leads to most comments being trite, and some wrong. Outside of that, comments have not been a problem mainly because they are almost non-existent, even when the code could benefit from them.
- esoterica 7y agoNothing enforces correct variable names and descriptive types either, why would you expect those to be more consistently accurate than comments?
- lmm 7y agoThey're amenable to automated refactoring, and if you change a type or variable name in one place you're forced to update it everywhere else that uses the same thing.
- JamesBarney 7y agoComments rot, but so does everything else such as type names, tests, variable names, field names, designs, architectures, etc.
- marvin 7y agoYep - it doesn't help much with a method that's named EmptyCacheToPreventBlugblagCongestion() if external circumstances have stopped the blugblag from ever congesting any longer. So discipline in maintaining the intent of the code is required even if you never write a single comment.
- lmm 7y agoTests, types and field names get checked on build.
- JamesBarney 7y agoIf someone adds functionality to a type so the name isn't really applicable anymore I don't think the build catches that.
- lmm 7y agoAs soon as you form something that should conform to the type (according to its name) and find that it doesn't, you notice the problem, and then you fix it once and for all (because the type is defined in one place). So yes, you can have misleading type names in the codebase, but there's a natural pressure to correct them, in a way that there largely isn't for misleading comments.
- njharman 7y ago(as others have pointed out here and every where) Comments are NOT for making code understandable. The things you mentioned are for that. Comments are for things like 1) explaining why this thing that looks wrong or dumb, really isn't. 2) explaining what method/function/class/whatever is suppose to do. Because code can be correct, understandable, and still wrong.