I’m a believer in s/w documentation. I realize that view is not shared by all s/w developers (especially in the Agile world in which we live), but in my opinion, generating documentation for your code is just like generating tests for your code: it’s 100% part of being a professional s/w developer. It’s your responsibility, and you should take pride in it.
I was reminded of this today and smiled inwardly when I came across the following statement in Section 7.1 of Python’s excellent documentation about its documentation:
“Python’s documentation has long been considered to be good for a free programming language. There are a number of reasons for this, the most important being the early commitment of Python’s creator, Guido van Rossum, to providing documentation on the language and its libraries, and the continuing involvement of the user community in providing assistance for creating and maintaining documentation.”
I could not agree more. I’ve gone to that Python documentation literally 1000’s of times. Where would we be without it? OK, maybe its not 100% fair to compare the documentation requirements of the Python language to that of the s/w widget that you are currently building, but I still think the analogy is there: Documentation must be created, and it must be created by people.
The documentation and tools to search for documentation that we have as developers today are astounding. From simple Google searches, to StackOverflow, to formal documentation for Apple and Android platforms, Python, etc. This documentation is NOT self-created (nor is self-creation as a philosophical construct possible — debate for another day). This documentation was created by all kinds of contributors who took time and wrote it. Some of it was created by people who were paid to do it specifically. Some was created by the developers as part of their development. And bunches and bunches of it was created by the open source, project, and forum communities across the interweb.
Documentation is a major key to both usability and maintainability. Why? I’m generalizing here, but if you are a developer on a team, it’s likely that the code you developed will be:
- Interfaced to and used by others (either other developers or users), and
- Maintained by or at least shared with other developers
In my opinion, the code plus some sort of documentation that describes the intention behind the code is critical to help others use and maintain it. The more your colleagues and users can determine on their own, the less you have to get involved later on. The classic win-win.
And guess what?
Six months from now when you yourself open that module back up, you may be looking at the comments/documentation yourself to figure out just what the ‘h’-‘e’-‘double-hockey sticks’ you were thinking when you wrote that code.
So what does documentation look like?
Well, that’s really a project dependent question. However, what I can say is that the minimum set of documentation for all source code should be:
- A header block at the top of files/modules and for all classes and functions within files that contains a description of the file/module/class/function, its inputs and outputs, and any design and use assumptions and considerations. For example, it’s useful to note when a particular module is not performing any range checking because its intended use is in a system that checks in a different layer.
- Correctly commented code. The only thing worse than uncommented code, is incorrectly commented code.
A little more on the topic of commented code…What about the concept of “we are developers, we should be able to read the code and figure out what it does.” Well…I agree completely. I think judicious use of comments inline may be useful (again as long as they are correct), but not absolutely necessary. However, what IS important inline are comments that describe intentions or the “why’s” that are not inherently obvious from the code itself.
So what other kind of documentation should be produced?
Again, its project dependent, but here are some guidelines:
- Developer and User Documentation: Overall developer or user level documentation for an application/library/language is best created manually and published in a web-based format. For example, the 3 that I mentioned previously: Apple, Android, and Python. In addition, I think it’s best if the “source” for the documentation is actually created in some markup/down text format, kept under source code control, and then rendered and published via automatic tools to a Wiki, direct to web server, or some other web-based service. This is not absolutely necessary, but I think its a real solid idea. This allows easy tracking and publications of differences between releases, plus rollbacks when documentation errors and issues are found.
- Modules/Classes/Libraries API Documentation: For modules/classes/libraries that are to be used as part of larger systems (i.e., they have an API), there should be API documentation, and it should also be web-based. Normally I think the best approach for this documentation is to use a tool that auto-generates the API documentation from comment-tagged source code, such as Doxygen and PyDocs. This is not always possible given the particular language for the project, but these methods should absolutely be employed when available.
- README’s and Release Notes: README’s and Release Notes should be in text or web-based format. Also, these should be generated automatically (or mostly automatically) from the SCM tool diff’s. Why do extra work each release? Take some time and write a script that will get the README or Release Notes directly from parsing through the SCM tool differences. Maybe you can’t get it 100%, but you can get it close.
So what about good old-fashioned Word or other offline documentation format? Well, sometimes given the circumstances, it’s still the proper format. However, given the way we as developers use documentation, it’s usually undesireable. It’s inherently unsearchable and difficult to manage in an SCM world. But again…sometimes its the only way.
That about wraps it up for me, for now…