Here I am, again bashing agile methods…
One of the aspects of the agile development model is that code should be self documenting, so there is no need to write a (proper) documentation.
There is only one problem: self documenting code don’t work. The reason is quite simple: when your code is your document, new developers will get into code before getting the whole picture. Joel Spolsky once complained (correctly) that code is hard to read than write and that’s why we end up (on big projects) with five or more functions that count spaces on strings. Remember when you got your new job, working in the language you always dreamt? Did you remember your excitement and how much do you want to prove you could do it (not only to management, but to yourself)? Well, that’s when you start the process of “five functions that do the same thing”.
That’s why you should never EVER use code as reference. The correct way to develop software is write the API first, documenting it and THEN moving to code. You don’t need to think about how to do what the function will do, but you need to know what parameters it will take and what it will return. This should keep away from the code (you can use some application that can extract special comments with this information, like doxygen or NaturalDocs) and then show this before letting anyone moving into code. Also, it should be easily available all the time, so current developers will know all the available functions and not reinvent the wheel.
