14 ms·
I saw someone quip (on twitter, I think) many years ago something like: "A junior engineer writes comments that explain what the code does. A mid-level enginee
by renhanxue 2y ago
I saw someone quip (on twitter, I think) many years ago something like:
"A junior engineer writes comments that explain what the code does. A mid-level engineer writes comments that explain why the code does what it does. A senior engineer writes comments that explain why the code isn't written in another way."
(except punchier, of course. I'm not doing the quip justice here)
- abc-1 2y agoI 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.
- 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.
- mschuster91 2y ago> A senior engineer writes comments that explain why the code isn't written in another way. And C-level engineers write a comment "X hours have been wasted on refactoring this code. Should you decide following the example of your priors, please increment this counter." Sometimes, even what appears to be an utter hack job actually is the best you're gonna get.
- steveBK123 2y agoThere's also the comments that tell you why the code does something obviously stupid but needs to continue replicating this stupid behavior because something else depends on it behaving this way.
- paulryanrogers 2y agoThis is the way :mando: If it's not answering why or at least providing a very concise how to very verbose code, then it's just adding noise
- saurik 2y agoThat sounds like "explain[ing] why the code isn't written in another way" where the other way is "the way you are right now thinking it should be as you read this: the way that isn't obviously stupid".
- steveBK123 2y agoI'm thinking less in "way the code is written" and more "the way the code works". That is things like cases it doesn't support, or weird results in some cases. One example is a shop I worked many years ago that had a function which did time conversion on date times without adjusting the date portion. Obviously, objectively, wrong. However the callers to this function expected this errant behavior. Actually changing it to behave correctly would require a coordinated change. Putting that comment in place prevents a new hire from going "oh this is obviously wrong!" and fixing it, causing an outage.
- belorn 2y agoI find that purpose of comments is to give context to the written code. Sometimes the context explains what the code does, and more often it explains why, but the best comments gives me the reader an insight so that I can have a intuitive feeling for what the author are writing.
- anotherevan 2y agoCursor cursor = getCursor(); // Cursor.
- erik_seaberg 2y agoI have seen a linter that requires class User { public String getName() { ... } } to have a doc comment explaining what getName does and also what it returns. Before git, they sometimes needed to see who wrote it and when.
- pjerem 2y agoWell, so, does this method return the login name of the user ? Or is the "name" field in fact a company convention to return firstname and lastname concatenation ? Oh and if it’s that, what will be the concatenation order ? It doesn’t seems like it’s a parameter but is it configurable somewhere ? Is this automatically defined somehow ? Is it hardcoded ? Or is there a name field in the database and if yes, what does it represent ? Etc …
- franciscop 2y agoWithin the code you'd have `return this.user.firstName + ' ' + this.user.lastName;` or similar, which can explain the details of how it works when you look into it.
- DanHulton 2y agoI'm not super opposed to that, honestly. Doc comments are coloured differently from code, and really help you scan through a file quickly to find the next function. It honestly doesn't take more than a couple seconds to write, and (I find) it really helps readability enough to be worth it.
- wrwatson 2y agoI think of comments as an apology to the engineer reading the code. I'm apologising because the code isn't obvious, or the language not sufficiently expressive, or the good-idea-at-the-time no longer is. Ideally I wouldn't need to write many comments, but I often find myself sorry things are not simpler.
- atoav 2y agoIn the end a comment should be like a shortcut that allows people to understand your code faster or a reminder why certain choices were made. You are right in spirit to say sorry when the code cannot be self-explainatory, but consider that sometimes even if the code is self explainatory, comments can help your reader to see the grand picture faster or to avoid interpersonal ambiguity by allowing you to use two different ways of phrasing a thing.
- incontrol 2y agoWhen I feel the need to add a comment, I convert that piece of content into the named function.
- kaoD 2y agoSo how do you document what is not in the code?
- tubthumper8 2y agoObviously in the function name! void vendorReturnsDataInInvalidFormatAndButShouldBeResolvedByVendorOpenTicketXYZ_123ExpectedResolutionQ42024(String input) {} /s
- kwhitefoot 2y ago> writes comments that explain why the code isn't written in another way." Exactly! I have written code that required comments five times as long as the code itself to defend the code against well meaning refactoring by people who did not understand the code, the domain, or the care needed to handle large dynamic ranges. I have also written substantial functions with no comments at all because it was possible and practical to name the function and all the variables so that the meaning was clear.
- yxhuvud 2y agoI've also written that kind of comments, and then promptly had it refactored by people not reading comments.
- klyrs 2y agoIt's true! If you come across a well-documented and complex piece of code, it's always easier to delete it all and write a simpler (and less correct) replacement than reading all of that code and documentation. And since your replacement is simpler, you're free to delete the inapplicable documentation that you saved so much time not reading! If you didn't back that documentation up with some tests to reflect the necessity of that complexity, this is an avoidable tragedy. But if the junior then comes in and deletes your tests because they don't pass, that's a firin'.
- kwhitefoot 2y agoIn the end we had sufficiently good tests to detect such foolishness. But even that isn't good enough because if the result of the test is merely slightly off some people will just adjust the assertions!
- cesaref 2y agoJunior programmers tend to either document nothing, or document everything. With experience you realise that you just want to document the unusual stuff, and as you get more experienced, you realise there is less and less unusual stuff, so the amount of comments drop down. So, less comments wins out, but faced with a code base without comments you have to inspect it to tell the difference between a beautifully crafted piece of brilliance or a totally flaky codebase written by a bunch of newbie hacks.
- lawn 2y ago> and as you get more experienced, you realise there is less and less unusual stuff, so the amount of comments drop down. This is a common experience when I use a new language or framework. At the start I comment a lot of things because I think it's useful for future me, but as I learn more I realize that many of the comments are redundant so I end up removing them.
- andoando 2y agoYou have to consider who the comments are for. Senior engineers comments are more useful for senior engineers, but the junior comments will be more useful for junior engineers.
- seanw444 2y agoI don't know. Senior engineers may understand the point of the code already, and "why it's not written a different way." The comment could be explaining to the less-experienced devs why they shouldn't waste time on another intuitive-at-first-glance approach.
- david-gpu 2y ago> A senior engineer writes comments that explain why the code isn't written in another way I suggest providing that sort of high-level decision information in a separate design document. This sort of documentation is written before the code and is presented/discussed with management and peers. That is how it was done at a couple of companies I worked at and it was very effective. Naturally, this was done at the feature level, not on a function to function basis.
- solidninja 2y agoThat still needs discipline though - or you end up with N half-finished Confluence pages describing the intention behind the design, all of which are now out of date (and naturally in completely different places). The best way I've seen to keep track of changing things is to have the design linked to the ticket somehow (and if it's a link, then that needs to be a permalink to something that will not go away in a year's time).
- anhner 2y agoI understood that to mean "I've tried doing it x way and it didn't work because y." rather than the functional part. At that point, why not keep the documentation together with the code?
- bccdee 2y agoThen you end up with a design document that corresponds to the code as it existed conceptually before v1 of that code was even written. By the time v1 is written, the design doc will be slightly out of date; by the time the code reaches v3, the document is more than 2 versions out of date. The nice thing about comments is that they're in the code. You can't update the code without at least looking at them; that's more visibilty than you'll get from anything else.
- david-gpu 2y agoDesign documents were updated as the code changed, obviously. Changing the code without updating the documents would not pass code review if somebody was shortsighted enough to try.
- MyFirstSass 2y agoTrue! Also i sometimes also do "yes this looks weird, but it's because : somebugtracker.issue"
- throwaway14356 2y ago...but if it is regex we are all juniors.
- retrochameleon 2y agoI resonate with that example. It's usually about a piece of code that didn't turn out the way you wanted to due to an issue. If there's a literal github issue or source I can link, I'll include the URL in case someone checks later and it's no longer a blocker. Somethings I include brief explanations or links to a particular piece of hard-to-find documentation.