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.
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.
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 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?"
That is to say, sure most code is obvious. I don't work on most code. I work on the parts that need fixing.