Thursday, 4 September 2008

Documentation

For code reuse, it's really important that a programmer is able to return to some code and use it without fear of some strange repercussions. Documentation is a necessity in our job. We are all lazy and none of us want to document our code. I'm terrible for not even commenting most of the time, but what I use is something that I think makes returning to my code bearable, and something that I can always follow. There are certain areas where I think I should add comments too, but usually, I think that code that has long identifier names and makes each step in the algorithm as obvious as possible, is better than comments that can go out of date. Instead of commenting in an *.h file about how to use a library, I write some use cases. It's almost like a really watered down test-driven development.

Benefits to relying on readable code: doesn't go out of date, takes less time to write/document, helps you not make stupid mistakes a lot of the time.

Hinderences: no overviews, some people demand comments, can be non-obvious even if you think it is.
Post a Comment