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.
Comments
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