[thelist] Basic Documentation Questions

Peter peter at poorbuthappy.com
Fri Feb 8 10:45:00 CST 2002


>-What types of things should be documented?
>-How does one go about documenting? (For example would one use comments
>within the code? A separate "documentation document"? Both? Other
>alternatives I haven't thought of?)

OK, there are basically a few levels of documentation:
- docs for other coders that will work on your code
- docs for the users of the system (if it has web based administration for
example)

Docs for other coders should include:
- short overview of architecture of the system
- list of all the main functions (or objects if doing OO), and what
arguments they take and what they give back. This is often coded in the
code as comments, and automatically generated from that.

Comments in code are a MUST, and should always:
- explain what a piece of code does
- explain any strange quirks of the code

Always add comments to the code AS YOU GO, don't even try doing it afterwards.
Peter




More information about the thelist mailing list