General

There are large variations in the amount and character of documentation for software development projects. MATLAB-specific style issues are concentrated in the internal documentation intimately associated with the code files, particularly comments and reference pages. Documentation of a software routine should clarify what it is doing, as well as define the required and optional inputs and the available outputs. Helpful documentation is aimed at a knowledgeable but not necessarily expert reader who is new to this program, yet familiar with the MATLAB language.

Where possible, the documentation should be generated from the m-file with little effort. The document should have readability features that make it easier to read than simple unformatted comments. In the case of the MATLAB product, this means using the Publish feature.

Provide Well-Written Code

The best documentation for a program is clean code. Comments cannot justify poorly written code, nor can they make up for code lacking appropriate name choices, good layout, or an explicit logical structure. Such code should be rewritten.

Document Each Module Before or During Its Implementation

Development projects are rarely completed on schedule. If documentation is left for last, then it will get cut short. Such documentation is often too little, too late, or even absent. Writing some documentation early assures that it gets done, and this practice will probably reduce development time. Writing at least some of the documentation before coding will also encourage you to think more about the functionality and interfaces of the modules.