An important aspect of software engineering, and perhaps computer programming in general, is to generate human-readable text (along with your machine-readable source code) that explains how the software works. Some of these ideas could be gleaned by an experienced programmer studying the source code, but it is generally unwise to assume that someone else (or you, years down the road) will be able to understand all of the good ideas and design that went into the programming by just studying the source code. The two classes of human-readable documentation to help narrate your software and design to humans include (a) comments in the source code and (b) programmer's documentation that sit as separate documents alongside the source code.
Here are some examples of good programmer's documentation:
World Tax Planner - I wrote this document over fifteen years ago when I was working in industry and was given a project that had no documentation whatsoever. It took me about a month of studying the source code to figure out and write this most basic overview of how the program worked. The documentation is relatively simple and brief, but after I wrote it, it meant a month of time saved for all subsequent programmers. Which also meant that we could then transfer development of the software to another set of programmers without embarrassment, which was extremely helpful in terms of the company's business plan. (There is an interesting story here, if you ask me in class. Just ask me about the World Tax Planner project.) If you skim through the document, you can imagine what a difference it would make having versus not having this document. Note that it is actually very short, but that it provides a useful, concise description of each of the major components, and how they fit together. Remember: I was give raw source code with no such explanations whatsoever. Imagine the difference this document would make.
EyeDraw Programmer's Documentation (PDF) - My lab is a bit unusual in terms of the development of research software in that I require my students to write programmer's documentation for their projects. This specific document then made it possible for other students--and an eye tracking manufacturer that we collaborate with--to pick up this code and extend it for other purposes that then further extended the impact and scientific contribution. Without the documentation, after the students finished and left, all of these ideas would have been lost forever. The source code is also quite well-commented and downloadable at the EyeDraw Website.
EyeMusic Primer (PDF) - This is unusual programmer's documentation in that it intersperses technical discussion with aesthetic and philosophical reflections on an avant garde electronic music project. It was written by Troy Rogers, now a Ph.D. student in electronic music at the University of Virginia. It is an outstanding project document, though the technical components could be better separated from the rest of the content. (Note that some interesting and important technical content comes at the very end.) The document is a good example of how it is reasonable to ask anyone developing a system, even artists and musicians, to document their code and provide programmer's documentation. It is also an example of how I will find you and hold you accountable if you develop a system in my lab but then try to leave without documenting your system. (He graduated and moved to Virginia and I did not let go of my demands until he provided this excellent document.) That he provided it meant that we were able to then continue with the project, which ultimately helped him further advance his career. (You can read more about the project at the EyeMusic Website.)
A. Hornof 1-19-10