Issue No.04 - July/August (2010 vol.27)
Diomidis Spinellis , Athens University of Economics and Business
DOI Bookmark: http://doi.ieeecomputersociety.org/10.1109/MS.2010.95
The basic principles of good code documentation include the avoidance of repetition, the coexistence of code and its documentation, the documentation of all artifacts, and a preference for clear code and automated processes to explanatory documentation. Existing tools can help us by extracting documentation from specially formatted comments and by formatting code listed in documents. We can also automate the generation of bespoke documentation with a custom-made tool. When you document code, strive for completeness, consistency, effortless accessibility, and an automated low-overhead generation process.
comments, documentation, principles, tools, best practices, javadoc, POD, software engineering
Diomidis Spinellis, "Code Documentation", IEEE Software, vol.27, no. 4, pp. 18-19, July/August 2010, doi:10.1109/MS.2010.95