14.5 Source Code Aspects

14.5.1 Source Code Documentation – a Philosophy

Requirements. Design. Test. There are boundless numbers of small projects where no formal (sometimes just no) documentation exists for these items. However, every software project has source code. Thus, it is worth looking at this topic in somewhat more detail (especially from the point of view of the individual programmer – for example, you). The ideas expounded here are aimed at two groups in particular:

• Novice programmers
• Experienced programmers who believe that documentation is for quiche-eaters and Ada developers

Both tend to have a very myopic, narrow view of program writing and development. Everything is done from their point of view, for their (often, immediate) convenience, in the easiest, quickest fashion. In many cases, the source code "documentation" includes the files submitted to the compiler. The content and format of such documentation depend on the...