Code Conventions and System Development

Naming Conventions

• 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

• 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.

Error Mechanisms

Source Code Control using 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

• 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

Finding Memory Problems using Purify

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"

Profiling using Quantify

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.

/**
 * [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 { ... }; 

1. Make sure every item appears exactly as it does above.
2. 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.
3. Please provide references to all related classes or topics in the @see section.

/**
 * 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

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

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

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

/**
 * [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);

1. Make sure every item appears exactly as it does above.
2. 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.
3. Every parameter and the return value should be documented as in the example below.
4. 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.

/**
 * 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

make doc

When you add a new file with documentation...

Idiosyncracies of DOC++

• 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:
   ....
  };