实用：源代码注释模板

Source Code Documentation Templates

 

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