The larger point of the original post is that good writing skill outlasts the acronym of the day, and has enduring value; documentation is but one. Another value of good writing skill is that it tends to disicpline one’s thinking and communication in general.

A final tidbit from the late Edsger Dijkstra: “Besides a mathematical inclination, an exceptionally good mastery of one’s native tongue is the most vital asset of a competent programmer.”

In my experience the worst code is often the code that needs comments the most. Sometimes both of these things are about being rushed.

I think some developers get an ego boost out of it. It gives them a (false) sense of skill/power that other people need their help to quickly see what their code is about.

Um, guys, anybody who knows anything about programming isn’t impressed. People can’t read my sloppy handwriting either, that doesn’t mean what I wrote is brilliant just that my handwriting isn’t as good as 5th graders.

Time and laziness aren’t excuses. It dosen’t take any time to put a one line comment above each function and a short paragraph at the top of each source file when you are done.

… which is exactly what you have when all of your precious documentation is out of date and irrelevant the second it is created because it is never kept up to date.

Here are 13 tips on how to comment your source code so that it is easier to understand and maintain over time:

http://www.devtopics.com/13-tips-to-comment-your-code/

A document is a single point of information for your code base that can contain more verbose descriptions and diagrams… things you don’t want to see in the source code. Code comments are good at describing “What does this do?” but a document is needed to explain “Why was this done this way?”.

Your code should document itself, to some extent.

that is, where you’re not on a component boundary, then very often code itself is the very best form of documentation – its important to make sure that you can write that clearly

Because moving to management means running with the pack. Prevailing pack wisdom for the last decade or so has been that programmers are overpaid, under-motivated, and over-valued, so they should be ever more ‘productized’.

Garbage In Garbage Out

I can definitely see the case for making time for documentation – I’ve had to pick up code sometimes that I wrote ten years ago (yes really) and add new features – I’d long since forgotten what I’d done and why I’d used a particular or strange way of tackling a particular problem! The presence of a few comments to highlight something out of the ordinary is the difference between updating the code cleanly and updating it and adding new bugs.

So I say, get over YOUR bad self Bob and keep the shop clean.

Then pay me more, use real project management techniques, Business requirements -> technical design -> Development -> validation life cycles.

Don’t come to me the week after you need a miracle and expect me to walk on water – that sh*t takes preparation

If you want maintainable code, you have to be prepared to pay for it. If you want functionality NOW, then get over your bad self.

The downside is that it takes up time.

Better to slip one deadline and do it right than slip every future deadline when people have to maintain your jibberish code.

“There is no downside to documenting your designs.”

The downside is that it takes up time. Sometimes you are working under a deadline and you don’t have that time. There are always trade-offs.