Revision History

The professional way to manage and document code changes is to use a source control tool. For simpler projects, use the following guidelines.

The revision history block should go at the very end of the m-file

Revisions should be described thoroughly, and a desire not to inconvenience the user with excessive scrolling at the top of the file should not be made a hindrance to good documentation.

Give the revision history the appropriate heading, followed by a block comment

Block comments are collapsible and save the space and effort of adding a % to every line.

Each entry should begin with the revision date

Begin each revision history entry with the date in ASCII-standard form (YYYY-MM-DD). If more than one author, follow the date with a slash and the name.

If the entire description of the revision for that date will fit on the same line, do so (with a colon and space separating the date/name from the description). Otherwise, start the description indented on the line below. Separate changes should start on a new line.

% Revision history:

%{

2000-01-01 

    v0.1 released and uploaded to file exchange (this line should be

    included in the released version).

2000-01-02: reformatted to comply better with the style guidelines.

2000-01-05/New Guy

    added two examples.

    fixed bug when implementing default value for first input.

%}

Every m-file should have its own revision history block

Ofttimes a project will have multiple functions and scripts. While together they may only have one help block, for example, each file should have its own revision history at the bottom.

Use in-line revision comments

In addition to or in lieu of a revision history block or revision block entry, put a comment with ASCII date, author, and change at the places in the code where you make a change.