View Single Post
Old 04-21-2011, 03:16 PM   #9
Location: Cambridge, MA

Join Date: Nov 2010
Posts: 23

My thoughts on this are biased by my training in Agile development environments, but here's my two cents on one way to incentivize programmers to write documentation (if you'll stretch the definition a little ):

My favorite type of documentation is an automated unit test suite, and the best way to get developers to write documentation and keep it up to date is to show them that writing automated tests for their code has benefits for them in the actual software development process. Commenting and documenting always used to end up a low priority for me because I was never sure if I'd end up keeping my code, changing it, or even throwing it away later, as my requirements or understanding of the problem changed. Plus as noted above there's not much external incentive to write them. So I added comments as an afterthought and often let them get out of date.

When I learned test-driven development, I found that my code got much cleaner and easier to maintain if I wrote unit tests at the same time as production code. Plus it gave me nice documentation; if I forget what a method does the best way to understand it is to read through a well-written unit test.

Of course, some algorithms are more testable than others (it's really hard to write a unit test that documents a dynamic programming algorithm in my experience), and it's hard to write tests for some of the more script-y things we have to do in bioinformatics. Some things just aren't worth the extra effort to test too, although those are exactly the things that tend to come back to bite me later when I skip testing. Overall, though, I really find writing and working with tested code productive and satisfying.
cwhelan is offline   Reply With Quote