I've been working on adding documentation to Monorail and a thought has crossed my mind. When I'm writing documentation for each method I'm forced to do code review to understand how it works. That's interesting because code review is generally considered a good practice and often many bugs can be fixed early with it. Essentially having to write documentation after writing the method makes code review automatic.

Like a lot of people I'm pretty reluctant to do something I feel is redundant. Often I feel that way about doing code review. I understand it's benefits, but code often looks simple and I become too confident that it is correct (until debugging starts). At the same time I learned to appreciate good documentation and I try keep all my code well documented. Sure it's more work to write documentation, but figuring out how something is supposed to work a year (or a week) from now is even more work.

I'm happy to do code review to write documentation, but... There's always a but. It's usually very beneficial to write at least some of it for the method prior to developing it (what the method does and possibly how it does it) to produce better code. So I need to write documentation before writing the method to have better code and I would like to do it after the method so I wouldn't have to do code review by forcing myself.

One solution is to have only part of the documentation done prior to coding. I.e. describe code function, inputs and outputs, write code, and follow up by preparing examples on how to use the method and how it works. Another solution would be to have method explained in the design document and add documentation to the code after completing the method. In the second approach the code is written in the context of the design document and code documentation is written in the context of the actual code. I'm going to try both approaches and once I figure out which one works better (for me) I will write about it. I might even come up with another alternative.