The first point is the most important. And unfortunately it’s almost never done. Always write functional specs before you start writing code. Define your project clearly and also define what you would expect to see in upcoming releases of your project, even if they don’t make it for the first version. Then always update that document everytime your project changes. Keep it up to date.

This has multiple advantages. For one, it allows you to plan correctly your project. If you have to work with other people, that document IS the reference for the project. Not the code. Not everyone is necessarily a coder in your team (if you write it for a client, he certainly isn’t able to understand code). It also allows you to easily write a presentation of your project, since it’s basically what the functional specs are. You can take chunks of it to insert into the user documentation directly, or to make slides for a conference.

It may not be obvious at first, but writing a functional spec before anything else actually makes the process of writing an application both faster and easier. I would recommend reading Joel Spolsky’s take on the subject, it is quite interesting.

I’ve been doing a fair bit Test Driven Development recently which works out to be quite similar. Except rather than documenting code via comments you document it via assertions in the unit tests. As a bonus testing becomes simple very simple; just run the unit tests. Also a great way to force yourself to thing about what you’re about to program before starting on the actual production code.

It’s no silver bullet, but certainly worth experimenting with for a few projects. I know it’s changed how I approach development work for the better (even if I don’t follow it all the time ; – ).

I was talking about technical documentation of function, classes and methods etc which is quite clearly noted. Furthermore I was actually quite careful to avoid mentioning any specific processes/procedures as the style of technical documentation will vary depending on the type of project and requirements.

A lot of devs can be quite arrogant and not accept the feedback from others. The problem with this is that if you want to be a great dev (and not just good) you need to continue learning and you cannot learn how to better yourself unless you listen to what others have to say about you.

Great post Mike.