> Why is it that software engineering is so against comments?
Good question. Funny thing is, I worked for a company that mandated that every method be documented, which gets you a whole bunch of "The method GetThing(name) gets a Thing, and the argument 'name' is the name of the Thing". Plus 4 lines of Doxygen boilerplate. Oof.
Of course, I've seen my share of uncommented, unreadable code. And also code with some scattered comments that have become so mangled over 10 years of careless maintenance and haphazard copy-pasting that their existence is detrimental. Many of the comments I come across that might be useful are incoherent ungrammatical ramblings. In large projects, often some of the engineers aren't native English speakers.
My point being that writing consistently useful comments (and readable, properly organized code) is hard. Very, very hard. It requires written communication skills that only a small percentage of engineers (or even humans in general) are capable of. And the demand for software engineers is too high to filter out people who aren't great at writing. So I guess many people just try to work around the problem instead.
Comments can convey hard-won information. Often developers will spend hours digging into an issue and then see a configuration or subtle change as the end result. That inocuous little bit of code is some of the most expensive, and brittle, code in the code base, but there is nothing to suggest it.
They might attempt to capture that knowledge in a git message, but that is destined to be burried in the sands of time.
> the 'legacy' code has way more knowledge embedded in it than it might seem.
Cannot agree more, but when knowledge embedded only in the code and not in comments/commits and documentation it is a problem even if you don't plan for re-write.
It is very disappointing to hear from otherwise good programmers statements like: "good code doesn't need comments (and my code is good)". As a result we have code where some line can captures hours of research and/or discussions, but there are no comments and commit logs are too brief. After a year even an author usually cannot say why it was done this way.
My current employer makes the useless code comments mandatory. They do not need to make sense or be useful; the requirement is that they exist. Fortunately, they pay me enough that I am not looking for other jobs over it.
No, I'm looking elsewhere due to the many other aggravations that are not worth the salary.
Not only are businesses training younger developers to do this, but they are training older developers to expect it. Of course it is going to bleed over into the real world.
> Comments are mostly useless in a machine-generated and machine-consumed file. They are indispensable for humans, because they are a link to what machines are not doing.
But comments are often code smell—a crutch for poor identifier naming and design. If your names and design are well thought out you rarely need comments and the consumer of your code should be able to understand it using the statically checked source alone—-versus manually having to parse your unchecked human language documentation.
It's frighteningly common, and more likely if only 1 developer is working on something. CS students comment far too much, but I would expect a monstrous chain like this to have at least -some- documentation.
The only comments I ever find useful are the "unprofessional" ones - things like "WTF, FooCorp are complete dicks and didn't implement the Blah spec properly, so now we have to work around their shit here". Without those kinds of comments it can be hard to understand the motivation behind broken-looking code that is actually broken by necessity.
What you write in your first para is so self evidently true, at least to me.
I simply cannot comprehend the mindset that views comments as unnecessary. Or worse, removes existing useful comments in some quest for "self-documenting" purity.
I've worked in some truly huge codebases (40m LOC, 20k commits a week, 4k devs) so I think I have a pretty good idea of what's easy vs hard in understanding unfamiliar code.
> Comments cost essentially nothing to add to your code and can save it from an early death and complete refactoring by the next guy who comes along.
Whatever their benefits are, this is not true at all. Comments are expensive to write and maintain. They are VERY VERY expensive to maintain because there is no automated way to test them.
> It's sometimes useful to preserve commented out code just because it represents some idea.
Then put a fucking comment saying this: "this commented out code below is to preserve idea FOO". Leaving commented out code without a real comment is just showing how unprofessional you are (or how you want to keep your job by trying to keep a knowledge-silo in your head).
This was a thing at my last job. The lack of comments always made me cringe. While not every line needs a comment, there's a reason why comments would be useful, especially in security software.
I learned a lot of bad habits there and I'm glad I no longer work there.
Their excuses were literally "no one reads comments" "no one keeps comments up to date" "my code is self documenting" etc.
This. Comments and documentation are pointless unless they are audited and vetted somehow, then there is the extra cost associated with maintaining them. Managers who don't know better think its just a bit of extra work that the developer does up front, but that is pointless without the above.
> And then you end up with a codebase which indicate A but comments which clearly spell out B, and you as a maintainer have no idea what to believe.
Can you name a few examples where you encountered this? In my career (30 years programming) I've never seen it. I believe it's a common, poor excuse for not writing enough comments.
The benefits of comments are well-understood. For me personally they often helped compensate sloppy code, (non-obvious) assumptions and prevented bad solutions because I reconsidered while writing (embarrassing) comments.
when you have to maintain a large codebase modified thousands of times in 15+ years, every single comment is invaluable.
I'll happily be "so brave" and reiterate a simple truism of software development -- comments are the battle cry of terrible developers.
They are the crutch of people who can't read code: "Add more comments because otherwise I can't make sense of what the statements are doing." It is the English speaker demanding that every French passage have an English translation, rather than simply learning French.
They are the crutch of people who can't write code. "My code is a gigantic, illiterate mess, so instead read the comment at the top that has no guarantee of being robust or accurate."
Bringing up mathematicians and Knuth are both irrelevant distractions. Software development in the modern world is a very structure, self-describing affair, or at least it should be. Comments are the short-circuit from having to figure out how to do that.
Well, I inherited a codebase where all comments fell into two groups:
1) Copyright notices and brief (1-2 line!) file-level descriptions at the top of each file and
2) Comments that the code needed to have in place in order to run properly... Delete the comments and things break. I am not kidding.
Oh, no documentation and no unit tests either. We started adding unit tests and found that things like number rounding failed.....
Years later we are still replacing the old code as fast as we can. The obvious things including braindead security issues, were just the absolute tip of the iceberg.
Nowadays I write my documentation first, then code, then at least some tests.
Over-engineered, massive codebases: job security.
reply