13 ms·
I do all of the above. Summary comments are incredibly helpful and have been validated by empirical research. Too bad many have drunk deeply from the Clean Code
by abc-1 2y ago
I do all of the above. Summary comments are incredibly helpful and have been validated by empirical research. Too bad many have drunk deeply from the Clean Code koolaid and can’t be saved.
- Prickle 2y agoI was taught to not leave comments in finished code. I have regretted following that lesson ever since.
- acbart 2y agoIf code were ever finished, then perhaps this would make sense :)
- spacechild1 2y agoWho taught you that!?
- Prickle 2y agoI was specifically taught that good, readable code could explain itself; that it would make comments redundant. Therefore, comments should only be used for things like psuedocode, or as help for fellow developers during dev. Then, they should be removed once the code is done. But yea, not a good idea.
- thayne 2y agoThis is an example of taking something that is contextually good advise, applying it to all situations, which turns it into bad advise. If you can make your code more clear, so that comments aren't necessary to explain what it does or how it works, that is probably (but not always!) something you should do. But that doesn't mean you shouldn't have comments. At the very least there should be comments explaining why (or why not) things were done a certain way.
- RandallBrown 2y agoI have almost never run into a situation where a comment was better than a well named function or variable. It happens occasionally, but it's usually a sign that I'm doing something wrong.
- moring 2y agoThis is fine. A problem arises when you assume that this will always be the case, for all developers, and then mandate that they omit comments, _without checking if your assumption is true for their case_. IMHO that rule can be generalized: Whenever you make rules for other devs, make sure that the assumptions on which those rules are based are true, lest you interfere with their work in a negative way.
- atoav 2y agoThere are indeed those situations where a comment would not increase the clarity of the code. But one shouls be careful not to mentally think of this as a zero sum dichtomy, where you either have well named functions XOR you have comments, because in reality choosingn both is often the golden path to success. The danger is of course that code that is totally obvious to you now will take far more time to become as obvious later, be it to your future self or to your psychopathic lunatic co-worker who knows where you live. So very often code can be made more readable by adding comments, even if it is just saying the same thing with other words, just by reducing ambiguity. Comments can also bridge higher level concepts in a good way, e.g. by you explaining in a few lines how a component fits into a concept that is spread out over multiple files etc. In the end code is text and like regular prosaic text you can both make it harder to understand by not mentioning things or by mentioning too many or the wrong things. This is why it is not irrelevant for programmers to be good and empathic communicators. Sure in the end readability doesn't matter to the computer, but it certainly matters to all people involved.
- exe34 2y agowell-named works great while you're writing the code. come back to it in a few years, or hand it over to somebody new, and you would realise that what looks like a good name to you means nothing to somebody else.
- atoav 2y agoThat is like saying: "A perfectly good road needs no road markings". The point of of good comments is that they make the code faster to read and less ambigous. While good code should indeed already be readable and unambiguos, I have rarely seen code that couldn't be made even easier to understand and faster to parse by writing the appropriate comment. But of course you will have some individuals who think it is cooler not to, and they are probably the same people who think use after free bugs can be avoided by the shere willpower of the solo-male-genius that they are.
- netdevnet 2y agoCode explains the what but not the why. And even then, the what might not be so clearly obvious. This is one of those blindspots devs have in that they believe their code to be good and obvious to everyone but in reality it is not even good and obvious to their future selves who will be the ones maintaining that code
- dspillett 2y ago> I was specifically taught that good, readable code could explain itself; that it would make comments redundant. Good readable code removes the need for comments about what the code does, if the working of the code needs extra explanation then perhaps it is being too clever or overly terse, but there are other classes of comment that the code simply explaining itself can't cover. Some of my comments cover why the code does what it does, perhaps linking it to a bigger picture. That could be as simple as a link to work ticket(s) which contain (or link to) all the pertinent details, though I prefer to include a few words of explanation too in case the code is separated from whatever system those work items are logged in. Many comments state why things were not done another way. This can be very similar to “why the code does what it does” but can be more helpful for someone (perhaps your future self) who comes along later thinking about refactoring. These can be negative notes (“considered doing X instead, but that wouldn't work because Y or interaction with Z” – if Y and Z become irrelevant that future coder can consider the alternative, if not you've saved them some time and/or aided their understanding of the bigger picture), helpful notes for future improvement (“X would be more efficient, but more complex and we don't have time to properly test the refactor ATM” or “X would be more efficient but for current use patterns the difference would be too small to warrant spending the time” – the “but” parts are not always stated as they are usually pretty obvious). A comment can also highlight what was intended as a temporary solution to mitigate external problems (“extra work here to account for X not being trapped by Y, consider removing this once that external problem is fixed” or “because X should accept Y from us but currently doesn't”).
- f1shy 2y agoIF the code is self-explanatory, then the comments are redundant, and is ok to delete them. But from time to time, there are things that are at least not so obvious in the code. Then is good to leave a comment. That could be used to see how good a language is for specific tasks. If you need to write lots of comments, maybe you have the wrong language.
- dodos 2y agoI had a professor in college who would grade you down if there were any comments in your code.
- forgotpwd16 2y agoPerhaps professor was fed up with over-commenting (comments made up a large part of submitted code), especially if comments were like in https://news.ycombinator.com/item?id=41506466 https://news.ycombinator.com/item?id=41506466. Unless the course is "practical software engineering" or similar, that good programming practices are a focus, and if the why/why-not parts can contribute to better assessment, an associated paper can be asked.
- dspillett 2y agoSounds like a concrete example of the phrase “Those that can, do. Those that can't (try to) teach.” Far from true for all teachers, of course. That and “those who actually use power are likely to be those who shouldn't have been given it”!
- readthenotes1 2y agoI have regretted when you fail to follow that lesson. I did a survey once in about 3/4 of the comments were either wrong or useless. Examples: //Add 1 to x x+=1; //Add 1 to x x+=2; //Seconds per normal day x = 86400; -- "Why not" comments are incredibly valuable except they suffer from explanatory decay as much as other comments. The hope behind Intention Revealing Names is that the dissonance will be too great for the subsequent developers to ignore when they change the code. Of course, that isn't always true.
- g-b-r 2y agoAn outdated comment is at least a very strong signal that the code might be wrong And, you definitely had little experience with under-documented code
- GianFabien 2y agoFor me the quality of comments, somewhat based on the metrics that @renhanxue mentions, is a code smell. If code is poorly commented (by my standards) then I treat the actual code with suspicion.
- dspillett 2y ago> An outdated comment is at least a very strong signal Also: if the code and the comments appear to disagree, there is a reasonable likelihood that both are wrong in some way.
- gus_massa 2y agox = 86400 If I were forced not to write comments, I'd write that as x = 24 * 60 * 60 and let the compiler optimize that.
- hansvm 2y agoWhen writing it inline, I like this approach. I like even better when these things have names. Something like `std.time.s_per_day` or `time_utils.s_per_day`. Then in the one place they're defined, use a pattern like the above to make them easy to reason about.
- imp0cat 2y agoCode is never finished, only abandoned.
- hi_hi 2y agoIf you're commenting out code, don't If you're commenting about the code, do. There's a huge difference in the value between one or the other.
- __MatrixMan__ 2y agoI like two of the three, but what is the advantage of commenting what the code is doing, when you can use a Trace or Debug message for that instead?
- PlunderBunny 2y agoNot the person you are replying to, but I would say that: - The code 'tells you' what it does - The comment for the code tells you what the author intended it to do. The gap between the two is where bugs can be found.
- readthenotes1 2y ago"The comment for the code tells you what the author intended it to do." Not quite. The comment for the code tells you what the author of the comment understood the code to do when hen wrote the comment.
- PlunderBunny 2y agoIt could be that too, but I think that presumes an order - that the comment was written after the code. If the comment was written before the code, then it would describe what the author was trying (intended) to do. Which also implies an order of course.
- g-b-r 2y agoYeah, absolutely check who wrote a comment before relying on it It's luckily rare for people to add wrong comments, though (and those who do should be publicly fustigated). By the way, please never state something as it were the truth if you're not sure that it is. Saying "I think" is perfectly fine, and might save people days of investigation.
- kristiandupont 2y agoNot the comments I write. I don't write what the code does or even what "I understand the code to do". I explain choices, especially ones that the next developer or my future self is likely to misunderstand when looking at the code.
- seanmcdirmid 2y agoWe could have the best of both worlds if comments could be easily hidden, or better yet, just additional meta-data on rich text code. But nope, we can't get away from ascii.
- readthenotes1 2y agoTrouble with comments is that they drift from the code over time because most people do not update the comments - - based upon my surveying production code bases. If they are hidden, it will drift even quicker and become even more useless faster
- convolvatron 2y agoi think in sean's proposed world we'd have metadata about that too! the comment in the context it was written in would be available, as well as all of the surrounding changes that potentially invalidate it. as well as potentially a whole discussion thread about what they meant when they wrote it, and suggestions about how to change it.
- seanmcdirmid 2y ago...and the main reason people don't like comments is because they clutter up the code that gives them the truth of the matter. But yes, if they aren't in your face forcing you to look at them rather than the code, then they are slightly more likely to not be ignored when the code is changed. It would be nice if they could be like footnotes, or boxed out-takes, that could be pushed to side notes. We have had the typography, even if it was just markdown with a rendered code reading mode.
- shiroiushi 2y agoThis is caused by poor or nonexistent code review practices. Reviewers should be ensuring that related comments are updated if code functionality is changed.
- yen223 2y agoI would urge developers to err on the side of too many comments over having too few comments, even if there's a risk of them going stale. I can deal with drifting comments, but I can't deal with missing comments.
- hughesjj 2y agoI got some flak at a prior job for saying I had some quibbles with clean code (a few years after I had read it), and I'm glad this opinion is more popular today. There's so much cargo culting hype with "best practices" and style, I hate it. Same with how overly dogmatic people were with OOP paradigms when it came out (remember using anonymous interfaces to pass a function around in java?). Same with the functional backlash to that. It's fun and enlightening to go ham on any particular style/framework/philosophy, but actually living by dogma in prod gets kinda dangerous and imo is counter to the role of a senior+ engineer
- AtlasBarfed 2y agoThe very term "best practice" is such a loaded term. It implies: 1) empirical measurement compared to a large number of alternatives ... the empirical measurement or study is never mentioned: because they do not exist 2) the best practice is valid in all measurements and criteria of comparison: performance, elegance, simplicity, correctness 3) since there is no data, the reasons for why the practice was designated best are rarely even explained 4) nor are the circumstances or individual or source of "best practice" detailed 5) it will always be the best practice: it is the BEST! It CANNOT be improved. So we have an unsubstantiated, unargued, unsourced, non-authoritative, exaggerated declaration in virtually every case of "best practice"
- answerheck 2y agoCopy that. CC has done a lot of harm in some ways.
- appplication 2y agoYes I write comments like a maniac. Long doc strings that are informally written. It’s more important for me to say what I need someone else (or future me) to know about a function and its context than it is for me to have some beautiful, sterile 300-line autogenerated soulless docstrings.
- answerheck 2y agoYes, we should all be kinder to both others and to future me (you). Do we know who will be maintaining this code? Obi-Wan meme: Of course I know him. He's me!
- kazinator 2y agoI write detailed git commit messages like a maniac. Git commit messages are better than comments, because they tag the specific baseline of code where a decision was made, and you can write multiple paragraphs to explain something (including all the "why not"), without cluttering the program text. The problem with comments is that they also pertain to a revision that existed around the time they were written, but they stick around, pointing to newer revisions, perhaps falsely. They add clutter. Unless you use a folding editor, comments can separate pieces of code so that you see a smaller window of the program. One line of code can be touched by many, many commits. Each of those commits should have something to say about that, and all that talk cannot possibly be put into a giant, ever-growing comment next to that line of code. In regard to my previous point, a lot of that talk won't even be relevant to the current version of that line! I've taken the view that the thing I'm developing is a git repo, not the source tree. A source tarball is just something for building and deploying, not for development. If someone wants to understand why something was done, they must use the repo, and not a source tarball. If they insist on just working with the source snapshot, but ask questions that are answerable in the git history, I cannot support them.
- worik 2y ago> I write detailed git commit messages like a maniac I do not think that helps much, in the general case > The problem with comments is that they also pertain to a revision that existed around the time they were written, but they stick around, Comments do require maintenance. It is part of professional practice
- cjfd 2y agoThis 'empirical research' is highly doubtful. The first question to ask is what the code with summary comments looked like. While summary comments can sometimes be helpful, this is mostly the case in functions that are relatively long. A question that always arises in that case is whether it is a good idea to split them instead of commenting.