wiki:StandardizingNamesRecommendations
Last modified 10 years ago Last modified on 05/06/2009 11:21:34 AM

Recommendations made by TCT (May 6 2009) related to Standardizing Names Proposal

The original proposal can be found at StandardizingNames

The earlier recommendations from the Apr 1st TCT meeting (overwritten by the TCT May 6 meeting) can be found here

This proposal applies to variables that are exposed to database, such as these that are used in the formatters.

1. The names of the C++ variables and their corresponding names in the database should be consistent to the extent possible.

Examples of existing inconsistencies:

C++ database
visitTime dataObs
exposureTime expTime
airMass airmass
photoZP PHOTZP

Known, well defined cases where the names may be different:

  • Scope name in the identifier variables (eg id vs sourceId). There will be cases where C++ uses a short name such as "id" to avoid redundancy (eg, source.id is preferred over source.sourceId). In such cases, trivial composition is allowed: the corresponding database column names will be prepended with the appropriate table name, for example sourceId in the Source table.
  • per-filter variables: in C++, these will likely be represented as arrays, and in database these arrays will likely be flattened. To facilitate this, the corresponding column names in the database will be prepended with the filter name, example: uAmplitude, gPeriod.

2. Naming columns representing uncertainty: the name of the corresponding column should be postfixed with "Sigma", "Rms", "Vrs" etc depending on the kind of uncertainty

Example, raSigma, bMagRms, xVrs.

Comment 1: the postfix Err currently used in database can be easily confused with error flags.

Comment 2: the order of columns mentioned in the original proposal is useful for database, especially for presentation, but we don't need to enforce it in C++.

Comment 3: 'Sigma' better than 'Sig', 'Sig' might be interpreted as 'Signal'.

3. Many rules originally proposed and discussed on April 1st are already part of the standard. These rules should be consistently applied.

This includes:

  • Names should start with a small letter
  • Avoid using short, non-descriptive names
  • Use camel casing
  • Capitalization (Ccd not CCD)

4. Glossary shall be created

Official glossary will help. It will serve as example how to name variables.

5. The fundamental quantity being described should appear first in the name...

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.

  • Ex: "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

This is a recommendation, not a rule.

It is too difficult to re-factor existing code, and there is no obvious programmatic way to enforce it.

Open issues

  • abbreviation for declination (dec vs decl). Attaching model name would solve this. This needs discussion.
  • Names must not explicitly include units. In cases where fundamental property is involved (such as calibrated/uncalibrated, eg skyADU) and non-trivial conversion is required, it is useful to indicated that property in the name. This needs discussion
  • default values / null values