this post was submitted on 20 Jul 2025
669 points (99.0% liked)
HistoryPorn
7030 readers
134 users here now
If you would like to become a mod in this community, kindly PM the mod.
HistoryPorn is for photographs (or, if it can be found, film) of the past, recent or distant! Give us a little snapshot of history!
Rules
- Be respectful and inclusive.
- No harassment, hate speech, or trolling.
- Foster a continuous learning environment.
- No genocide or atrocity denialism.
Pictures of old artifacts and museum pieces should go to History Artifacts
Illustrations and paintings should go to History Illustrations
Related Communities:
founded 2 years ago
MODERATORS
you are viewing a single comment's thread
view the rest of the comments
view the rest of the comments
It's funny to look at this code because a large fraction of current programmers (perhaps a majority?) think that comments are a "code smell", an indication that the code is fundamentally flawed. Granted, in that language code really couldn't be self-documenting with descriptive variable and method names, but it was still sufficiently reliable and maintainable to get men to the moon and back.
No unit tests either lol.
This is my first time hearing that anyone thinks comments are code smells. What's the logic behind that supposed to be?
Fla already explained the rough logic behind it, but I also think a big part of it is that people have a habit of approaching advice like this too dogmatically. For example, guidance that says "commenting your code is not a substitute for sensible structure and variable names", and someone may read that and go "I shouldn't use comments, got it". Certainly I have seen (and written) code that overuses comments in a manner that the average comment has pretty low information value — for me, this was because I was inexperienced at writing code other people would use, and comments were things that I felt I should do, without properly understanding how to do it. Like if there's a line that says
a += b, I don't need a comment that says "# adds b to a". That misses the point of comments entirely, and would make important comments harder to see, and the code harder to understand.Another area where I often see this overly rigid mindset is the acronym "DRY", which means "don't repeat yourself." It's a decent principle, and it's helped me to identify larger structural problems in my code before. However, some people take it to an extreme and treat it as an absolute, inviolable law, rather than a principle. In some circumstances, repeating oneself would improve the overall code.
If I had to choose between code that had sensible variables and structure, but no comments, and code that was opaque but heavily commented, I'd probably choose the former. However, in practice, it's a "why not both" situation. It's less about the comments than how well they're used, and identifying comments as a code smell may be an attempt to get people to approach code readability slightly differently and using comments more wisely.
That makes sense. I've certainly been guilty of excessively DRYing my code. On one hand, it's a fun little puzzle to work on. On the other hand, it's been making it very hard to quickly iterate, and that's especially bad for research code.
It only nakes sense to apply DRY principles when you find you keep having to copy paste the same code to muliple locations on your codebase, and its reasonably clear it will never diverge from eachother. In other words, apply as needed to maintain development velocity (and in turn stability).
Not an opinion i hold. But i've heard others say that code should be written in a way thats simple and easy to understand, e.g. variables/methods with meaningful names. Logic kept simple within aptly named methods that define what it does.
The stance seems to be that if you should keep code simple enough, or named well enough that comments aren't necessary in the first place (excluding niche situations).
I can even begin to imagine how I'd explain with only code how various hacks are necessary because of a bug in something it's interfacing with, or how various mathematical expressions were derived.
Yeah. Code explains how, comments explain why. I can see what happens, but I surely cannot see why someone thought this was a good idea. Please don't write
int addSomeSpecificFillerBytesBecauseTheLegacyAPICountsTheHeaderAsPartOfTheDataStructureAndTheCurrentAPIDoesNot()I ran into this when I was doing the Accessibility/VoiceOver stuff for an iOS app. VoiceOver is (or was at the time - maybe they've fixed most of the problems) buggy as shit in lots of weird ways, and I sometimes had to do strange things in the code to get things to work properly in VoiceOver mode. I would always add comments explaining why I had to do these weird hacks before I would submit the code. The guy approving our pull requests was a young developer solidly in the "all comments are bad" camp and he would always just delete my comments. Sometimes, because he wasn't even remotely aware of what VoiceOver was for or how it worked, he would also delete the changes I had made to get VO to work in the first place. For good measure, he also badmouthed me to our bosses whenever possible, calling me technically incompetent (because of the comments).
The fun part was when our app failed its annual accessibility review (badly) and he had to scramble to restore all my changes that he had deleted. He didn't restore my comments, though, which apparently led to us failing the following year's review as well because other developers deleted my shit, having no idea why it was in the app. He and I had both been laid off at that point so there wasn't any institutional memory of it at that point - another reason why comments are important, as they're essentially the only form of documentation that there's even a chance future developers will read.