3 ms·
I am always amazed how few developers document their code. I always hear: "I write code that is easy to read" - Great but well written code can't... tell you
by bbuffone 16y ago
I am always amazed how few developers document their code.
I always hear:
"I write code that is easy to read" - Great but well written code can't... tell you why it was done this way, what it is actually supposed to do, how people should use it, how people shouldn't use it.
"I don't have time" - When is a developers time constrained by typing? Unless you type one word a minute you have time type create documentation.
Documentation is even helpful when creating the code. As ideas or thoughts change medium... from brain to paper or to sentence form. I see the problem differently, which gives them better understanding before wasting time creating something that isn't going to work.
Documentation is also helpful for two other people: Those who are not you and your slightly older self.
- kscaldef 16y agoI'm always amazed how few developers _read_ documentation of the code if it's there. I've had multiple instances where I comment a section of code explaining why it's very important that a certain thing be done just this way (or that a certain thing _not_ be done), only to have someone else come through a couple months later and break things by making exactly the change that the comment said not to do.
- jshen 16y agodid you have a test for it?
- kscaldef 16y agoIn some cases, yes. More frequently this sort of thing has been performance issues (comment reading something like "don't do X here, or else it interacts with Y in a way that kills performance of the whole application"). Testing for performance regressions can catch stuff like this, but since that's not typically done for every commit, you can end up having to do significant forensics or trawl through hundreds of commits to find the cause.