I just finished the initial round of documenting my open source project, Oakfoam. Initially there were little to no comments, but I decided that this was unacceptable, so over the past couple of weeks, I have been slowly documenting my code. Now, every class and all its public methods have at least a brief line of documentation. I have recently gotten two volunteers for my project, so I think my timing has been rather good.
In order to help the process, I have been making use of Doxygen. It uses the familiar Javadoc “/**” style, whilst helping to compile nice HTML and LaTeX versions of the documentation. I highly recommend having a look at Doxygen for your documentation needs.
I have previously been rather averse to commenting code, believing that code should be understandable without comments. However, after my project has grown to over 10 000 lines of code, I’ve realised the error in my ways. I can now see the use in at least some documentation, especially for an open source project. Why should I expect everyone else to have to wade through my code and figure out what is going on? Hopefully this initial learning curve will be greatly lessened now. After thinking about it, I realise that you can’t expect to attract any contributors without some documentation to guide them. Oakfoam’s documentation is still a long way away from complete, but I do feel like I have reached a milestone.