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 3 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

3-4. Names representing methods or functions SHOULD be naturally describe the action of the method (and so will usually start with a verb) and MUST be written in mixed case starting with lowercase. Private member function names MUST additionally lead with an underscore.

Do not put a space between the function name and the opening parenthesis when declaring or invoking the function. 

class GoodClass {
public:
    void const getPublic() {}           // OK
protected:
    void const getProtected() {}        // OK
private:
    void const _getPrivate() {}         // OK
};

void getName() {...}                    // OK
void computeTotalWidth() {...}          // OK

Refer to Rule 3-10 for a discussion on the leading underscore requirement for private member functions.

Common practice in the C++ development community. This is identical to variable names, but functions in C++ are already distinguishable from variables by their specific form.

3-5. A name representing a typedef MUST be initial letter capitalized, camel-case with no prefix of the enclosing class.

typedef unsigned char Byte;
typedef unsigned long BitMask;
Byte smallMask;

This syntax is consistent with template type names and classes which are also similar in usage.

3-5a. A name representing a typedef SHOULD have a 'T' suffix if and only if necessary to disambiguate the typedef from a template bare name

If the typedef is a template specialization of a concrete type, the typedef name should typically include some indication of the parameter type (e.g. "typedef Image<float> ImageF;"). If the specialization uses an incoming template parameter, the suffix 'T' is preferred to using the specialized template's bare name, as the latter is very difficult to use correctly in C++.

3-6. Names representing namespaces MUST be camelCase with leading lowercase letter and based on component or directory name.

The original package developer will specify in the .cc file the preferred abbreviation to use and, optionally, also use it throughout his code. The original developer may consider using the following guideline to fabricate the name

  • remove the preliminary 'lsst';
  • concatenante the remaining fields;

  • if desired to make shorter, abbreviate each field while still maintaining a relevant word.

    namespace pexLog = lsst:pwx:logging;
namespace afwMath = lsst::afw::math;

Two options are available for using a namespace when defining symbols

  • Specify the namespace explicitly in the definition

    lsst::foo::bar::myFunction(...) {...};

  • Use an abbreviation for the namespace 

    namespace fooBar lsst::foo::bar;
fooBar::myFunction(...) {...};

Putting the definitions into a namespace block is not recommended: 

namespace lsst{
namespace foo{
namespace bar{     // NOT Recommended
   myFunction(...) {...};
}}}  // lsst::foo::bar

3-7. Names representing template types MAY be a single uppercase letter or a mixed case phrase, first letter capitalized in each word, indicating the desired type.

template<typename T> ...             // acceptable
template<typename T> ...                // acceptable
template<typename C, typename D> ... // acceptable
template<class PixelType> ...  // acceptable, user-defined class only

Common practices in the C++ development community. This makes template names stand out relative to all other names used. Note this rule applies to the template type, not template instances. Regarding the use of typename versus class, we will adopt the convention of using typename in all cases except where the intent is ONLY a user-defined class and not primitives.

It is recommended that template parameter names that are not a single character be suffixed with 'T' or 'Type' to distinguish them from other, concrete types.

3-8. Abbreviations and acronyms MUST not be uppercase when used as name.

exportHtmlSource();    // NOT: exportHTMLSource();
openDvdPlayer();       // NOT: openDVDPlayer();

Using all uppercase for the base name will give conflicts with the naming conventions given above. A variable of this type would have to be named dVD, hTML etc. which obviously is not very readable. Another problem is illustrated in the examples above; When the name is connected to another, the readability is seriously reduced; the word following the abbreviation does not stand out as it should.

3-9. Global variables and functions SHOULD be avoided and if used MUST always be referred to using the '::' operator.

::mainWindow.open(), ::applicationContext.getName(), ::erf(1.0)

In general, the use of global variables should be avoided. Consider using singleton objects instead. Only use where required (i.e. reusing a framework that requires it.) See Rule 5-7.

Global functions in the root namespace that are defined by standard libraries can often be avoided by using the C++ versions of the include files (e.g. "#include <cmath>" instead of "#include <math.h>"). Since the C++ include files place functions in the std namespace, "using namespace std;", which is permitted by Rule 5-41, will allow these functions to be called without using the '::' operator. In cases where functions are only available in the C include files, the '::' operator must be used to call them. This requirement is intended to highlight that these functions are in the root namespace and are different from class methods or other namespaced free functions.

3-10. Private class variables and methods MUST have underscore prefix.

[TBD In the future, commentary will be added on restrictions regarding single letter private functions.]


 

 

 

 

 

  • No labels