Home
About ISIS
Support
Download

ISIS 3

Documentation
Tutorials
Technical Documents

ISIS 2

Documentation
Tutorials
Technical Documents

Search

USGS

ISIS 3 Documentation


Style Guide

Object source code styles and conventions

Home

Introduction | Mandatory Commands | Useful Commands | Example Header | Example Implementation | HTML Quick Reference


Introduction: Conventions and Definitions of this Guide

Purpose

This guide has been generated for ISIS programming team as a style reference for writing in-code documentation to meet team requirements for consistency, content, and information dissemination. Serving as a reference for proper documentation structure for automatic generation of documentation in various formats, primarily HTML, is the primary focus of this guide. ISIS Applications have their own code and documentation style. Information for the documentation system maintainers will be provided in a separate document covering system level tags (such as @mainpage and @defgroup), directory structure, naming conventions, etc.

Conventions

In the tag lists (later in this guide), arguments will be surrounded with either < >s, [ ]s, ( )s, or { }s. These brackets should not be included in the tags when used--they are only used as a visual reference in this document.

Definitions

Mandatory is a pretty strong word... we will define here to mean use it if it applies. Many documentation components will always be included, such as CVS revision for files and category for classes. Other tags may not always be applicable, such as documenting return value and parameters for functions. Use your discretion, and have your documentation reviewed by a peer.


Understanding Our Audience: API verses Programmer Reference

There are two major audiences for our source code documenation. Two sets of documentation are maintained, one for each audience.


Naming Conventions

File Extensions:

Files and Directories

We will be using a UpperCamelCase syntax, where every new word begins with a capital letter, for all file names and most directory names.

Object Directories: All of an Object's files go into a directory named identically to the Object. In the case where the Object has several classes, one primary class (the parent, base, API) should be identified and used for naming the directory.

Subdirectories are not allowed for Object source code.

Files: Header and Implementation files are to name identically to the class they define. In the case where the file contains several classes, one primary class (the parent, base, API) should be identified and used for naming the file.

Naming user defined types and method names:

We will be using a UpperCamelCase syntax, where every new word begins with a capital letter, for all user defined types (classes, structs, typedefs, etc.), and method names, such as: ProcessByLine (class) and ProcessByLine() (constructor).

Naming variables:

All variables will use lowerCamelCase syntax, where the first letter is lower case and the beginning of other words are capitalized, such as: allRequirements.


Documentation Basics

Source Code Documentation Structure

Currently, the ISIS programming team is using the Doxygen documentation extraction software. Doxygen has extended the tag set of the javadoc documentation style, a systematic in-code documentation style that allows pertinent documentation to be extracted easily. Doxygen is just one of many software packages that are able to extract and use javadoc documentation for a variety of purposes, allowing us to take advantage of a wealth of documentation extractors, IDEs, and other tools on the market that make our lives simpler and more productive.

In order to be able to generate automatic documentation correctly and follow a systematic and consistent approach , each programmer must:

Date Format

Dates should always follow the ISO date format standard. Generally, you'll want to note the current date - use YYYY-MM-DD. See the complete ISO 8601 standard [190KB PDF] for the complete information. Use of this standard allows us to avoid internationalization issues and have dates that can be easily extracted by computer software.

Using HTML

HTML can be used anywhere in your documentation. Keep it simple. Doxygen will "interpret" your HTML, so you may not get the desired effect. Best advice, avoid attempting special effects by just using the basic HTML formatting tags - bold, underline, pre, code, table (caption, tr, td, th), etc. and only when really necessary. Better yet, consider using the formatting tags in the Other Useful Tags section instead of HTML. Your plain old text will be pretty nicely rendered into paragraphs with automatically linked items and other bells and whistles. Keep your source readable: minimize formatting.

Autolinking

Class, method, variable, and other entity names will be automatically linked in the documentation. To prevent this for a specific occurence of a name, use a percent sign (%) in front of the name. For example, if you have a class name "Histogram" and you want to prevent the linking of the word "Histogram" in your description because it is not referring to the class but to an actual histogram, use "%Histogram" to prevent the word from being linked.

E-mail addresses and web addresses are also automatically linked. If a web address is particularly long, put it on its own line.


Document History

Deborah Lee Soltesz2005-10-31 Fixed format instructions for @history (date and author were inverted)
Deborah Lee Soltesz2006-06-05 Updated @image use instructions and conventions
Deborah Lee Soltesz2006-07-29 Update CVS tags described in the guide so that CVS wouldn't automatically replace the tag with actual information when this document is checked in. (Replaced $ signs with ISO8859-1 entity, treating the $s as special characters).