No, comments tell me what you wanted to achieve. Code only tells me what you actually achieved.
Winston Royce's (fantastic) 1970 paper "Managing the Development of Large Software Systems" accurately anticipated how things would end up working 30+ years later in shops that try to use 'self-documenting' code as a substitute for good documentation.
Without good documentation every mistake, large or small, is analyzed by one man who probably made the mistake in the first place because he is the only man who understands the program area.
When system improvements are in order, good documentation permits effective redesign, updating, and retrofitting in the field. If documentation does not exist, generally the entire existing framework of operating software must be junked, even for relatively modest changes.
Add modern-day turnover rates on technical teams, so that the person who originally wrote the code is unlikely to be around to help with analyzing problems, and you've got an excellent recipe for the current chronic burnout status quo.
Why from a user level belongs in executable specifications.
Why from an implementation level belongs in comments, but that should be fairly rare. Most code shouldn't provoke the question "why on earth did they implement it like this?"
Most of my job is figuring out why things were built the way they were. That's the only way I can know if I'm making the right changes without breaking something else in the process.
That is to say, sure most code is obvious. I don't work on most code. I work on the parts that need fixing.
Comments
Code tells me what you wanted to achieve. Comments tell me why you needed to.
The problem developers have is they assume it's obvious why things are needed. It's usually not obvious 6 months from now, even if you wrote it.
No, comments tell me what you wanted to achieve. Code only tells me what you actually achieved.
Winston Royce's (fantastic) 1970 paper "Managing the Development of Large Software Systems" accurately anticipated how things would end up working 30+ years later in shops that try to use 'self-documenting' code as a substitute for good documentation.
Add modern-day turnover rates on technical teams, so that the person who originally wrote the code is unlikely to be around to help with analyzing problems, and you've got an excellent recipe for the current chronic burnout status quo.
https://www.praxisframework.org/files/royce1970.pdf
Why from a user level belongs in executable specifications.
Why from an implementation level belongs in comments, but that should be fairly rare. Most code shouldn't provoke the question "why on earth did they implement it like this?"
Most of my job is figuring out why things were built the way they were. That's the only way I can know if I'm making the right changes without breaking something else in the process.
That is to say, sure most code is obvious. I don't work on most code. I work on the parts that need fixing.