When I was coming up as a young VBA pup I was told again and again “all good programmers document their code,” and “constant documentation a good developer makes” and “blah, blah, blah document” and I hated it. I hated documenting, I hated figuring out something fun and then going back and explaining it to someone else in English. I always associated documenting code with reporting and testing as the vegetables of programming, I didn't like it but it was essential for success. The reason it was important, I was told, was because if another programmer had to work with your code you wanted them to know what they are looking at. You wanted them to be able to get right to work and not have to spend much time gearing up and learning the system. I believed this for much of my 27 years on this earth, but lately I have realized one thing, if your programmer needs documentation in order to be able to quickly pick up on what it is doing one of two things are true: either the programmer sucks or, more likely, your code sucks.
Now, I'm not talking:
//This method was created because the full select query was costing performance, so we made this one to call back only two values.
That type of commenting is important because sometimes you need to quickly remember why you DIDN'T do some things in ways that you usually would. We don't always research our bug trackers and dev logs before fixing something we perceive to be broken or done incorrectly. This way we don't change something that we did for a reason we may not remember.
I'm more speaking of:
//07/06/08 S. Chipps This method retrieves a dataset from the DB that contains the records that were entered between the two dates passed. First the values are tested to make sure the second is greater than the first then we insert them into the query to get the data we are looking for.
An oversimplified version of what I am talking about, but you get the drift.
Alright, so, there is no reason anymore to record who wrote the method (or function for you naked C folks), we have source control now. It's much more accurate when you are looking to throw some blame around, so sociopathic coders can't frame others for their crappy code. So, basically, writing manual for your code basically says that there is the chance the person reading it may not understand what they are looking at. There is no good reason for this, besides the fact that they are new to the field or technology. However, in that case, I think the best thing to do is allow them to figure it out for themselves or sit with them and explain it.
If you've been fortunate enough to witness a truly beautiful application, learning what a piece of it does is not a chore. Everything is exactly where it should be, the variables? Extremely self explanitory. The data? Corresponds with the variables. The objects? Exactly the same as the data. The methods? You can read the name of them and pretty much learn exactly what they do, if you're still curious look down... everything is done in the simplest, leanest, cleanest way possible.
What's my point? Stop documenting code, stop asking your coders to document, stop thinking that documentation is a staple in programming. Because it's not, everyone else has realized it. You shouldn't need to document how to install your application, how to set up your local environment, or what third party executables to run in what order before compiling the second time. If you find that is not the case then you're doing it wrong, and your time would be better spent fixing it rather than writing about it.
THE END
