Mere Code

Diverse Topics of General Interest to the Practicing Programmer

Documentation again

Documenting your code is not important. Well-documented code is not a thing to be desired nor a goal to be sought. A lack of documentation is not a problem to be solved. Everyone who tells you otherwise is lying.

What is important is that other programmers can easily understand your code and the intent behind it, and that you can understand the code and the intent six months later.

Documenting your code is merely a way of achieving that. It might even be necessary for it. But do not confuse interface with implementation and do not confuse what you want with how to get it.

Solve the problem of confusing, opaque code. Aim for code that can be easily understood. Document if necessary.

(it’s pretty much always necessary)

Comments

tekNico on 2010-07-06 15:14
So, document your code. ;-)