实用：源代码注释模板
| Languages |
| C | C++ | Delphi | Java | HTML | Makefile | Perl | Shell | SQL |
| Introduction |
Configuration Management tools usually supply a template standard for documentation when a new file is created. Here is a list of these templates which you can download for insertion into existing code.
There are two versions: one which is augmented with HTML codes to encourage you to place your documentation on the web and one which is plain text. The templates have been designed to be cut and pasted into your editor and to have chunks cut out if you do not feel the section is appropriate.
Where appropriate, a UML version of documentation has been used at an effort to introduce some commonality. However, for completeness, traditional code documentation is included.
| Generic File Header |
| Standard | Web Based | Description |
|---|---|---|
| Web CM File Header | CM File Header | This header is designed to be placed at the head of each physical files and contains a selection of SCCS keywords together with organisational information (Project etc). These inform you of the files status, ownership and version number. This particular example has C style of comments which you can change to the language specific commenting convention. |
| C |
Due to scoping rules, C programs are arranged into modules which are analagous to a package (as in Java or Perl). There is usually one semantic module per file which may contain many functions.
Global and static data definitions and initialisation and constant definitions are held in semantically grouped header files.
The standard makefile mechanism is used to coordinate the build process.
The two C specific header files are for the documentation of a C module (which is a related set of functions) and documentation of individual functions.
| Web-based | UML | Traditional | Example | Description |
|---|---|---|---|---|
| C Module | C Module | C Module | C Module | C module header. The traditional is based on the Unix man(2,3) format |
| C Function | C Function | C Function | C Function | Description placed at the head of each function within a C module |
| C++ |
C++ programs consist of a set of classes, most of which are compiled into libraries. These class libraries are analogous to packages.
Each class is declared in a per class header file with the suffix .h and implemented in a file with the suffix .C/.cc/.CC/.cpp (dependent upon the development environment).
Global and static data definitions and initialisation and constant definitions are held in semantically grouped header files.
The standard makefile mechanism can be used to coordinate the build process but, usually on NT platforms, this is automatically generated by the IDE.
As above, each file has the default configuration management header file, followed by the relevant CM header.
| Web-based | UML | Traditional | Example | Description |
|---|---|---|---|---|
| Class Definition (.h) | Class Definition (.h) | Class Definition (.h) | Class Definition (.h) | Description of class definition |
| Class Implementation (.cpp/.C/.CC/.c++ ) | Class Implementation (.cpp/.C/.CC/.c++ ) | Class Implementation (.cpp/.C/.CC/.c++ ) | Class Implementation (.cpp/.C/.CC/.c++ ) | Description of the class implementation |
| Delphi |
Coming soon. Seeking help from Nick Mappin.
| File Type | Description |
|---|---|
| None as yet | working |
| Java |
Java programs are usually documented using javadoc which ships as part of the relevant Java sdk and third-party tools. The header files below have used the annotations of the javadoc tool.
The javadoc tool collates all the comments from a series of .java files and produces and index page, giving an overview of all the packages, classes and their methods.
Inner classes can be declared with a standard class definition. These are documented using the same template as an ordinary class.
As above, each file uses the default configuration management file header , followed by the class header.
I have included UML style documentation here for completeness, however, there is a UML documentation tool specifically for Java Code (and C++). The Together/J tool from Object International, a free version can be downloaded from their site.
| Template | Examples | Description |
|---|---|---|
| Java Class File | Example | This is the documentation template for a Java class file. It can also be used for an inner classes. |
| Java Method | Example | Java Method documentation templates |
| Java Field | Example | Data fields in a class |
| HTML |
| Object | Description |
|---|---|
| HTML Header | Standard HTML Document header including all the relevant META keywords. |
| HTML Footer | Standard HTML Document footer including a selection of status keywords. |
| Makefile |
| Makefile | Example | Description |
|---|---|---|
| Makefile | Example | Makefile template. This includes the CM header too and has a nice (IMHO) example. |
| Perl |
| Type | Description |
|---|---|
| Perl UML Package/Class | This shows you how to write documentation using UML and is intended for OO Perl 5. |
| Perl UML Operation | UML header for a perl function. |
| Shell |
| Shell Programming | Description |
|---|---|
| Shell Program | Derived from the Rabbit book (you know that I mean), a good general purpose header for shell programs. |
| Shell Function | For those who like to write shell libraries of functions, a function header |
| SQL |
| Databases | Description |
|---|---|
| SQL Script Files | Much as above but with sql type comments |