Orbit Determination Toolbox (ODTBX) Wiki

Advanced mission simulation and analysis tool

Status: Beta

Brought to you by: jjkparker, keberry, kgetzand, lschlenker, and 2 others

QaCodingStandards

Labels:

Authors: Anonymous

Coding Standards

This page holds the coding standards for the Orbit Determination Toolbox.

Revision 0.4 2011-04-29 Allen Brown

The standards included here are:

ODTBX MATLAB Function Naming Conventions
MATLAB Function Documentation Standards

An example is attached.

Generally these standards are also applied to MATLAB classes. Exceptions will be noted.

Other possible standards for code-level (syntax and formatting), design-level (API or algorithm structure), or external data (input or output file formats) are not yet defined.

Background

This is the coding standards for the ODTBX MATLAB files. While “formatting alone does not make a good coding standard”, the documentation of a MATLAB .m function is more specialized than for other languages because it is free-form but serves multiple purposes:

1. Support and integrate with the various MATALB Help Systems,
2. Support the users of the function (the clients),
3. Support of current and future maintainers of the function (the developers).

These are written so that a developer with any level of MATLAB or ODTBX experience could follow them and get their code integrated with ODTBX.

ODTBX MATLAB Function Naming Conventions

• Keep the name short but keep it consistent with other functions and intelligible
• A good guideline is to keep the name pronounceable
• The use of uderscores in MATLAB function or class names is under discussion.

Capitalization, Case, and Numbers

• The function name should not begin with a number.
• The function names should not contain other punctuation.

• Note: We are discussing whether underscores should be used to distinguish between MATLAB functions and classes.

• The ODTBX standard for case is that functions should be all lower case.

• However, there are several examples of mixed case where capitalized letters are used for readable abbreviations.
• Note: We are discussing whether MATLAB classes should be named with a different style than MATLAB functions, such as "CamelCase" with no underscores.

• Allowable mixed-case conventions:

o Technical terminology:

o RK for Runge-Kutta, or extensions (e.g. RK4 or RKF78)
o JD or MJD for Julian Date or Modified Julian Date
o DCM for direction cosine matrix
o Capital D can be used for dimension
o Specific algorithm or system abbreviations (e.g. WGS, IAU, GPS, etc). These must not be ambiguous in the ODTBX world and must be consistent with other functions.

• Numbers in the function name are allowed. Generally the following is true:

o The number denotes a specific dimension (e.g. 2D or 3D)
o The number denotes an algorithm (e.g. WGS84)
o “2” has a special use where it signifies a conversion from one thing to another (e.g. kep2cart)

MATLAB Function Documentation Standards

Each MATLAB function in the ODTBX will have at least the following:

A Function specification
A MATLAB Help System documentation section
The ODTBX NOSA license

Function Specification

This must be the first line in the file
The function name must match the .m filename
If the length of the entire function signature is over 80 chars then cut the argument list between arguments using ellipses “…” and continue onto the next line for readability.
Allow the built-in MATLAB editor’s indentation formatter to align the continued arguments with the ones on the line above (Ctrl-I).

Rationale: Fighting an editor’s built-in formatting usually introduces more unintended changes over the life of a project. These changes, if they accidentally occur, will always have to be evaluated as formatting-only changes or true content changes and this takes time and effort.

MATLAB Help System Documentation

General Rules for the MATLAB Help System Documentation:

This section must be a single contiguous set of MATLAB .m comments.
All lines begin with % in the first column, including "blank" lines used for whitespace.
Lines are limited to 80 columns.
Use spaces and not tabs inside the comments for proper formatting. Rationale: The comments look different than intended and may be less readable when other developers use different tab settings or different editors.
This section must appear immediately after the function specification with uncommented whitespace between them.
When the function’s name is referenced anywhere in the help system its case should match the function name.
Each of the items in this documentation should be separated with at least one line of (commented) whitespace.
The order of the items noted below should be followed in the documentation even if some optional items are skipped.

Item 1: Summary Description

This is a single full sentence description of this function that will appear in the contents browser.
Start the sentence with the function name. The convention is “subject verb…”, e.g. “MYFUNCTION Computes the range between a and b.” Note that the case of the function should match the function name.

Item 2: Detailed Description

This is a user-focused explanation of what the function does.
There is no tag or label for this item. It simply begins after the summary description.
Multiple sentences and even multiple paragraphs could be used in order to adequately explain the function’s behavior.
If there are multiple ways to achieve the function’s behavior then some explanation of the algorithm should be included. Remember that this documentation is primarily for the users of this function. Details only a developer would be interested in should be placed elsewhere.

Item 3: Input and Output Descriptions

Both the input arguments and output variables are described in a similar format. The inputs are described first, followed by the outputs. If either of the two set have no variables in function specification (e.g. function [] = x(y) or function [y] = x() ) then that section can be skipped. Each section is formatted as a space-delimited table format for readability.

Section ID: Each section begins with a one-line “INPUTS:” or “OUTPUTS:”
Labels: The next line is the column header labels for the section, it is:

VARIABLE TYPE SIZE DESCRIPTION
Order: The items in the section should be presented in the same order as they appear in the function specification. This includes all optional arguments.
Variables: These are the names of the variables as they appear in the function specification.
Type: This denotes the expected MATLAB type, double, char, cell, struct, etc.
Size: This denotes the MATLAB dimension of the variable in MATLAB convention. A scalar is 1, or 1x1. Variables that have one arbitrary dimension are 3xN or Mx14, etc. Multiple dimensions are NxM, NxMx3, NxMxP, etc. If dimensions of several inputs or output variables must be coordinated be sure to use the same chosen letter so you don’t create confusion. Chosen letters are up to the developer, but avoid X, O, and I. Always use lower-case “x” for the dimension designator.
Description: The description is one or more lines of text that specify the data in the variable. This must be complete enough so that a client can either properly construct or properly use the data. This is free-form except for the following:

o Optional inputs should have “(Optional)” at the beginning of their description.
o Units must be noted in parenthesis for every variable with no exceptions. For non-dimensional parameters use “(unitless)”, “(dimensionless)”, “(no units)”, etc. Abbreviations can be used if the meaning is clear from the description, e.g. “(km)” for a distance variable.
o Reference Systems (coordinate systems, time systems, etc.) must be included so there is no ambiguity. Time specifications can be more complex because they may require separate specifications for the date format (JD, MJD, etc.) and the time system (UTC, TDB, TT, etc).
o Any restriction such as dimension size, numerical ranges, etc. on a specific variable should be documented here or in the Limitations below where there is more room. Restrictions due to a combination of variables should be documented separately. Use a (see LIMITATIONS, below) comment for this.
o Any defaulted values should be explicitly noted.

Formatting:

o The variable names, types, and sizes should be spaced so they appear in a column under their respective labels.
o The description should start under its DESCRIPTION label. Multiple lines should also use spaces to continue as a “block” for readability.

Cells and Structs

o Be sure to document the expected type(s) and size(s) of the items in the cell array. Also note if there are any conventions on the type and location in the cell array.
o Be sure to explicitly describe every field in the struct. The struct itself should appear on a line by itself. Its fields should each be described immediately underneath the struct. Place a “.” before each field so they are easily identifiable as fields of the above struct. For example, if r is a struct with four fields:
VARIABLE     TYPE     SIZE   DESCRIPTION
r            struct   1      r contains the range measurements to 
                             the target from the installation in
                             the “installation reference” frame
 .x          double   1xN    X component (km)
 .y          double   1xN    Y component (km)
 .z          double   1xN    Z component (km)
 .t          double   1xN    measurement time (MATLAB serial 
                             time)

Item 4: Limitations (optional)

Any limitations of the algorithm should be documented separately so they stand out. The intention is to explain things to the user/client so that they don't run into this limitation in the first place, they aren’t surprised when this occurs, and they know what to adjust to avoid this limitation again.
Combinations of inputs that cause these issues should be documented here.
Formatting:

o Separate by one line of (commented) whitespace,
o Start the line with “LIMITATIONS: “
o Describe the ways this limitation can be encountered.
o Describe how the function will behave (different return values, any MATLAB errors, etc.) when this limitation is encountered.
o If possible, provide advice on what could be changed to avoid this problem when it is encountered. For example,” If this occurs, try reducing the XYZ threshold value to 10% of its former value.”

Item 5: Example !Input/Output Combinations (optional)

If desired, please have one or two simple examples with associated command line statement(s) and the expected output. This can be very useful for functions with extensive, or optional, inputs and/or outputs.

Item 6: Keywords (optional)

This must start with “keyword: ”
Each keyword should be a comma-delimited list
A single keyword can actually consist of multiple space-separated words
The line must end with a comma!
Keep (commented) whitespace before and after the keywords section
Content is up to the developer.

Item 7: See Also (optional)

This section documents other ODTBX functions or significant MATLAB functions that this routine relies upon. Placing them here allows the user to navigate through the help system. It is not required if this routine doesn’t depend upon other functions.

This reference section should be the last line in this set of comments before the license.
Keep a (commented) line of whitespace before this section.
It should begin with “See also “.
Items referenced should be space-separated names of other functions or classes.

ODTBX License, Copyright, and Help Reference

The [OdtbxLicensing] page describes the license that should be applied to source files. In summary, there are two parts:

1 A short reference to the license that is visible in the MATLAB Help system,

2 The longer license reference with copyright that should not be visible in the MATLAB Help system.

One line of uncommented whitespace separates these two parts. This short reference should be the bottom-most item displayed in the Help System documentation.

Revision History

A manually-maintained, file-specific, change log is not yet a standard on all ODTBX files. If it is desired, then this section should be separated from the License and other Help System documentation by at least one line of uncommented whitespace.

Example