Code Conventions and System Development

[ Style | Development | Documentation ]

Much of this page may be useful only to developers within Cornell CS.

Style

[ Naming Conventions | Code Formatting ]

Naming Conventions

Here is a list of C++ naming conventions to be used when adding to PREDATOR code.

All class and type names to begin with Capitals and break MultiWords with capitals, e.g., XxxAudioADT.
All variables to begin with Capitals, and break MultiWords with capitals, e.g., FuncMethType. (Loop variables will be small letters.)
All public class members to begin with Capitals and break MultiWords with Capitals, e.g., FuncMethType.
All private class members to begin with lowercase and break MultiWords with Capitals, e.g., schemaArity.
All global function names and public method names to begin with Capitals and break MultiWords with Capitals.
Avoid global variables. If absolutely necessary, globals should start with unique 3 letters reflecting type name (like Rel, Seq, Img, etc.), or Xxx.
All macro definitions to start with XXX_ and be completely capitalized. Wherever possible, macros to be replaced by inline functions.

Code Formatting

Remember the usual formatting guidelines .... break your code into small short functions, use indenting, comments, etc. The following specific details have been followed in PREDATOR:

For all functions/methods, the initial "{" sits on its own line.
For all code blocks, the initial "{" sits on the same line as the preceding "if", "while", etc clause.
Every "else if" or "else" clause is in its own line.

We have tended to use the auto-indent feature of Emacs to format our code.

Development

[ Error Mechanisms | Source Control | Debugging | Memory Leaks | Profiling ]

Error Mechanisms

Every non-trivial function/method should return an XxxErrCode. Currently, the possible values for this are XXX_OK or XXX_NOT_OK. Whenever a function/method is called, the return code must be checked. Whenever an error is to be returned, a suitable error message can be added to the error stack using XXX_NOTE_ERROR() or REL_NOTE_ERROR() macros.

Source Code Control using RCS

RCS is a simple source code control mechanism. Each of your source directories will have a pointer to an "RCS" repository directory. To get the actual .C and .h files, you will "check out" the files using the "co" command (see below). This will happen automatically the first time during installation of the s/w. Thus, you will have a local copy of every source file! Any checked out file has only read permissions. In order to update files, either change the permissions using "chmod", or acquire the lock on the file. Here's some information on how to use RCS.

co file : just gets the latest version of the file, but no lock
co -r1.23 file : checks out version 1.23 of the file
rlog file : shows you the history of updates to the file, including who currently has the lock on it. For files that have been around a while, this could dump a lot of info to yr screen, hence pipe it to more.
rcsdiff file : gives you a diff of yr current file versus the latest checked in RCS version. This is very useful if you are updating a copy without taking a lock on it, and someone else has updated it in the interim.
rcsdiff -r file : does an rcsdiff of your current file versus the specific version of the file.
man rcs; man co; man rcsdiff; man rlog

The following commands are only to update the RCS repository:

co -l file : checks out a file and locks it
ci file : checks in the file (you should first own a lock on it). You will be prompted for a check in message. Please put in something meaningful. Similarly, the very first time you check in a new file, you will be asked for a description of the file. This is no place for brevity :-)
rcs -u file : break a lock on a file. If the owner of the lock is someone else, then you will be prompted for a message that will be mailed to him/her.
rcs -l file : acquire a lock on a file.

Using a Debugger

As a system developer, one of the first things you will want to do is use a debugger. We have used gdb as the natural companion to g++. While personal preferences vary, we tend to use gdb from within emacs, because this provides a "visual" debugger without the hassle of a point-and-click interface. A sample .gdbinit file is in the top-level "utils" directory of the release. If you need to debug SHORE code too, make sure to use a version of the SHORE libraries that was compiled with debugging flags.

Finding Memory Problems using Purify

Purify has proven very useful in tracking down memory leaks and memory overwrites. In order to create a Purify'ed version of your server, use "make xxxpure" in the "code" directory. This will generate an executable called xxx.pure. Be warned that this is likely to be very large and run slower than the Mars Sojourner. Use xxx.pure just like the regular xxx PREDATOR server.

Purify tends to get confused because of the threads package used in Shore, and also because "uninitialized" data is sometimes "read" in a DBMS in order to be written. A sample ".purify" suppressions file is in the top-level "utils" directory of the release, and this reduces some of the warnings. You then have an option: you can either compile Shore with the USE_PURIFY flag --- this eliminates some of Purify's confusion. Optionally, you can pipe the output of the Purify'ed server through the "disinfect" script (which is also in the top-level "utils" directory). This removes many spurious messages. However, using this approach precludes the use of the graphical Purify interface. Instead, you should set something like the following in your .cshrc.

setenv PURIFYOPTIONS "-output-limit=100000 -free-queue-length=500 -chain-length=10 -cache-dir=/home/praveen/purifycache -always-use-cache-dir=yes -windows=no -ignore-signals=0xffffffff -handle-signals=0x00000400"
setenv QUANTIFYOPTIONS "-cache-dir=/home/praveen/qfycache -always-use-cache-dir=yes"

We have lacked the time to fully remove memory leaks, but this is a process that we are gradually undertaking.

Profiling using Quantify

Just like you created a purified version, create a quantified version using "make xxxqfy". This generates "xxx.qfy". Quantify comes with a nice graphical interface to view the results. We have not yet undertaken serious performance tuning, but initial efforts with Quantify were pretty useful.

Documentation

[ General Conventions | Class Declarations | Member Declarations | Function Declarations | Generating Documentation | Adding a New File | Idiosyncracies]

To facilitate automated code documentation by DOC++, PREDATOR code follows a standard designed to produce ample documentation of classes and members. Once the comments are in place, DOC++ scans the source files and generates HTML or LaTeX -based documentation for future developers. While we have only recently started using DOC++, we hope to soon have the entire code base commented appropriately.

No code should be added to the PREDATOR codebase without accompanying documentation. The conventions below must be followed to insure uniform results.

General Conventions

Every class, data member, and function member must be documented. Documentation takes place in .h and .java files only. Documentation in .cpp files, although very helpful for those reading your code, are not processed by DOC++.

All comments associated with a specific declaration, e.g., class, must preceed the declaration. Those that follow it (including those on the same line) will be associated with the next declaration.

Before checking in your code, insure that the documentation generated for your code is comprehensible and explicit.

Class Declaration Conventions

Every class declaration, even nested class declarations, must be preceeded by a comment of the form:

/**
 * [Memo]. (optional)
 * [Documentation]
 * @see [Related classes, topics, etc.] (optional)
 * @author [Your name and e-mail address] (optional)
 * @version [The date the code was checked in, e.g., June 1, 1997] (optional)
 */
class Foo : public Bar { ... };

Things to note about the comment:

Make sure every item appears exactly as it does above.
The [Documentation] section can consist of any number of lines of text which you deem necessary to understanding your class. The first sentence, i.e., all text preceeding the first period encountered, will become the memo of the class. This should be a meaningful and brief description of your class. The rest of the [Documentation] section should elaborate and provide all necessary details. To insure readability, preceed each line of the [Documentation] section with an asterisk, as in the example below.
Please provide references to all related classes or topics in the @see section.

Here is an example of a well-documented class:

/**
 * The parse structure for functions over audio types.  This class
 * encapsulates all the necessary information to parse an expression over
 * an audio object, including the ID of the method and any catalog
 * information required.
 * @see XxxFuncParseInfo, XxxAudioADT
 * @author Leong Kian Fai
 * @version June 1, 1997
 */
class ParseInfo : public XxxFuncParseInfo { ... }

Member Declaration Conventions

All class members must be documented, no matter how trivial they may seem. Documentation of a data member consists of preceeding its declaration with a /// comment; for example:

/// The method ID of the method relevant to this structure
AudioMethType MethType;

If the presence of /// messes up the autoindent on your editor, try //// instead -- this usually works fine. Comments which are on the same line, e.g.,

AudioMethType MethType; /// The method ID of the method

will not be properly processed.

If a data member requires more documentation than can be written on a single line, you may use the /** ... */ format; for example:

/**
 * The method ID of the method relevant to this structure.  It is important
 * to note that the value UNDEFINED will cause mass destruction, and its
 * use should be disallowed.
 */
AudioMethType MethType;

Function Declaration Conventions

Every function declaration must be preceeded by a comment of the form:

/**
 * [Memo].
 * [Documentation]
 * @param param1 [Description of what param1 is]
 * [...]
 * @param paramn [Description of what paramn is]
 * @return [Description of return value]
 */
XxxErrCode FooBar (int param1, ..., int paramn);

Things to note about the comment:

Make sure every item appears exactly as it does above.
The [Documentation] section can consist of any number of lines of text which you deem necessary to understanding your function. The first sentence, i.e., all text preceeding the first period encountered, will become the function's memo. This should be a meaningful and brief description of your function. The rest of the [Documentation] section should elaborate and provide all necessary details. To insure readability, preceed each line of the [Documentation] section with an asterisk, as in the example below.
Every parameter and the return value should be documented as in the example below.
It is not necessary to include the @author and @version fields for functions belonging to classes. But in the rare case of a global function, please include them as in the class example above.

Here is an example of a well-documented function:

/**
 * Action for the vibro-volume merge rule.
 * This is the action performed when the vibro-volume merge rule is
 * applied.  It transforms the two expressions into an equivalent
 * single expression.
 * @param InVExpr The incoming expression
 * @param RuleData Any data passed in by the rule firing
 * @param OutVExpr The resultant expression
 * @return The status code.
 */
static XxxErrCode VibroVolumeMergeAct(XxxValueExpression* InVExpr,
                                      void* RuleData,
                                      XxxValueExpression*& OutVExpr);

Generating Documentation

To generate the PREDATOR documentation automatically, type

make doc

in your $XXXROOT directory.

When you add a new file with documentation...

When a new .h or .java file is added, DOC++ must be made aware of it. Each directory in the codebase has a file called doc++.items. It is a list of //@Include: directives. Add your file to the list in its directory. It will then be processed by DOC++.

Idiosyncracies of DOC++

Since DOC++ is also free software from a research project, it has certain idiosyncracies to be aware of -- all the same, it is tremendously useful if you intend to have others understand your code.

Inheritance from a nested class can confuse DOC++ --- this required a 1 line fix in the source code of the DOC++ lexical analyser.
If there are multiple pieces of information on the same line, DOC++ has a bit of a problem figuring out which of them to associate the preceding comment with. So do not use the following format :
```
class Foo { public:
 ....
};
```
Instead, use:
```
class Foo { 
 public:
 ....
};
```

MAIL:: User support: predator-support@cs.cornell.edu Project information : praveen@cs.cornell.edu