DEPRECATED

This space is obsolete and unmaintained. The entire content of the DM Developer Guide is now maintained at https://developer.lsst.io .

  • Created by Unknown User (shaw), last modified on Sep 22, 2014

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 2 Next »

3. Naming Conventions

3.1. General Naming Conventions

3-0. Guidance on Selecting Names

  • The fundamental quantity being described should appear first in the name, with modifiers concatenated afterward. A rule of thumb is to ask what the units of the quantity would be, and make sure that quantity appears first in the name.
    • "dateObs," not "obsDate" for a quantity that fundamentally is a date/time of significance;
    • "timeObsEarliest" (or, "timeObsFirst"), not "earliestObsTime"
    • "nGoodPix" not "goodPixN" since this is fundamentally a number
    • There are some historical exceptions (e.g., expTime from the FITS standard) that must be preserved
  • Use care to select the most meaningful name to represent the quantity being described
    • "imageMean" not "pixelMean" if we are talking about the mean value of an image, not repeated measurements of a pixel
  • Names should not explicitly include units
    • "skyBackground" not "skyADU" to indicate the sky background level
    • "expMidpoint" rather than "taiMidPoint"; or "timeRange" not "taiRange"
  • Acronyms should be used sparingly, and limited to very common usages in the relevant community.
    • CCD, FWHM, ID, PSF, and RA would be fine as name fragments
  • Obscure abbreviations should be avoided: clarity is probably more important than brevity.
    • "apertureDiam" would be better than "apDia"
  • The Database Schema document should be reviewed for existing appropriate names
    • Check the authoritative DB Column names for the current Project in order to select consistent names between persisted C++ variables and their corresponding DB Columns. Refer to Section 3.3 Names Exposed to Database.

3-1. Names of user defined types MUST be in mixed case starting with uppercase. 

class Line, SavingsAccount

struct {
    float bar;
    int  yoMama;
} Foo;
Foo myFoo;

typedef Vector<Frame> FrameVector;

Common practice in the C++ development community. The capitalization rule for class names should be all words in the name capitalized, e.g., "ClassName".

3-2. Variable names MUST be in mixed case starting with lower case.

int lineWidth;

Common practice in the C++ development community. Makes variables easy to distinguish from types, and effectively resolves potential naming collision as in the declaration Line line;. Keep variable names balanced between short and longer, more meaningful. Use 8 to 20 characters as a guideline (excluding integer loop counters which may be as little as 1 character).

3-3. Named constants (including enumeration values) MUST be all uppercase using underscore to separate words.

Common practice in the C++ development community. 

int const MAX_ITERATIONS = 25;
int const MIN_ITERATIONS(23);
enum { HIGH_SCHOOL, GRAMMAR_SCHOOL, KINDEGARTEN };

In general, the use of such constants should be minimized. In many cases implementing the value as a method is a better choice: 

int getMaxIterations() {     // NOT: int const MAX_ITERATIONS = 25
  return 25;
}

This form is both easier to read, and it ensures a unified interface towards class values.

Note that this rule applies only to const variables that represent constants (i.e. those that would be set using an enum or #define in C); it does not apply to variables that happen to be determined at their point of definition, e.g.:

void foo(string const& filename);
float const r2 = r*r;           // radius^2

 

 

 

  • No labels