wiki:TypedefProposal
Last modified 9 years ago Last modified on 09/10/2010 08:38:14 PM

Typedef Naming Convention Proposal

Introduction

There are somewhat contradictory standards for naming C++ typedefs. Confusion about this topic has led to many different styles of names used in practice. This proposal attempts to codify a final standard for incorporation into the official C++ standards document.

History

Coding Standards

The written coding standards are somewhat contradictory: 3-1 says "typedef Vector<Frame> FrameVector" while 3-5 says "byteType type" despite claiming to allow "variables to have the same name as their type".

July 2007

There was a discussion on the lsst-data list about this between Robert, Ray, JeffB, and JeffK. (Subject name was "Type names within classes".) The consensus then of the membership of the CCB (despite the lack of a formal meeting) was that:

  • Convention had been to use Foo::FooPtrType (note initial capital).
  • This was redundant.
  • We should use Foo::PtrType (still initial capital and appended "Type").

JeffK said he'd update the coding standards at that time but apparently did not.

August 2007

Ray checked in his Policy implementation. He used Policy::Ptr instead of Policy::PtrType. Since the initial capital indicates a type, the appended "Type" was redundant. This usage follows that given in standard 3-1. (With a lowercase initial letter, as in standard 3-5 but not 3-1, Type is meaningful and necessary.) JeffB and I saw this and rather liked it, so I adopted it for the persistence framework, not noticing that this violated 3-5 and the unwritten July consensus. JeffB declined to change DataProperty::PtrType (which already followed the consensus) because of widespread existing usage.

October 2007

The fw package apparently adopted an ad hoc standard of Foo::FooPtrT (still initial capital, and with redundant Foo and T), which violates both the written and as-of-July-but-not-written standards.

Current Situation

We have:

  • An outdated and contradictory written standard that no one follows. [diaSourcePtrType]
  • A July 2007 consensus/CCB standard that appears to be followed by daf/base, pex/exceptions, and (mostly) ap. [PtrType]
  • Another ad hoc standard followed by afw. [DiaSourcePtrT]
  • Yet another standard followed by pex/policy and daf/persistence. [Ptr]
  • Perhaps another unapproved usage. [strIntMap]

Proposal

Robert and I and apparently Ray all agree that the pex/policy and daf/persistence standard of just choosing a capitalized, camel-case name for all typedefs, with no prefix of the enclosing class and no suffix of T or Type, is clear, simple, and non-redundant. It is consistent with standard 3-1. We propose that this be adopted project-wide, either by deleting standard 3-5 or rewriting it to explicitly state that typedef names are to be treated the same as other type names.

Add comment