News for hackers. Stuff that matters.
Re:Slow Down to Go Faster by bbuffone on Wednesday September 29, 2010 @11:39AM (#1739796)
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.

Re:Slow Down to Go Faster by kscaldef on Wednesday September 29, 2010 @12:26PM (#1739989)
I'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.
Re:Slow Down to Go Faster by jshen on Wednesday September 29, 2010 @01:59PM (#1740370)
did you have a test for it?
Re:Slow Down to Go Faster by kscaldef on Wednesday September 29, 2010 @04:19PM (#1740989)
In 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.