wiki:Programming Style Guide

Programming Style Guide for PET, version 1.0

Discussion:

  • Although starting symbol names with underscore conflicts with some recommendations for the C standard, i want to stick with it because i've seen no clash up to now

Indentation

  • Proper indentation and paragraphing are mandatory
  • Always use spaces for indentation, no tabs!
  • Use two spaces per indentation level
  • Delete trailing white space
  • Only a single statement per line
  • A line of code should not be longer than 80 characters
  • If you have to break a line
    • break after a comma
    • break before an operator
  • If a method does not fit on one screen then it is probably too long
  • Use spaces appropriately
    • Yes: grandTotal = invoice.total() + getAmountDue();
    • No: grandTotal=invoice.total()+getAmountDue();
  • No spaces around period or arrow (field/pointer access)
  • Minimise the use of vertical white space
  • Only use ASCII characters, or UTF-8 encoding, if necessary
  • put opening braces after function or method headers, if , for , etc. onto the same line
  • putting else onto a new line is recommended for long if--else statements

Naming Conventions

  • CamelCase for Classes (without leading `t')
  • Method and local Variable names should adhere to the C standard: small with underscores to separate multi-word names.
  • CONSTANTS all upper case, underscores to separate multi-word names
  • Avoid too long names to save horizontal space, if you can keep clarity
  • Do not abbreviate names by removing vowels where not necessary
    • append_signature(String signature)
    • appnd_sgntr(String sgntr)
  • Capitalize only the first letter in acronyms
    • loadXmlDocument()
    • loadXMLDocument()
  • Avoid names that are similar or differ only in case: sqlDataBase vs. sqlDatabase
  • Use is_ or has_ as prefix for methods/functions returning bool
  • The shorter the name of a variable, the smaller its scope!
  • data fields should start with an underscore, especially private ones

Documentation

  • Write comments that can be processed with doxygen
  • Pay attention to punctuation, spelling, and grammar to make reading easy
  • Keep comments in sync with the code

Programming Conventions

Constructors

  • Don’t put much work into constructors, write an init() method if necessary
  • Either implement an assignment operator and a copy constructor for a class or explicitly inhibit copying
  • Use the C++ keyword explicit for constructors with one argument

Declaration Order

  • Your class definition should start with its public: section, followed by its protected: section and then its private: section. If any of these sections are empty, omit them.
  • Within each section, the declarations generally should be in the following order:
    • Typedefs and Enums
    • Constants (static const data members)
    • Constructors
    • Destructor
    • Methods, including static methods
    • Data Members (except static const data members)
  • Friend declarations should always be in the private section, and the DISALLOW_COPY_AND_ASSIGN macro invocation should be at the end of the private: section. It should be the last thing in the class.
  • Method definitions in the corresponding .cpp file should be the same as the declaration order, as much as possible.
  • Do not put large method definitions inline in the class definition. Usually, only trivial or performance-critical, and very short, methods may be defined inline.

Class and Method Visibility

  • Be as restrictive as possible!
  • Use friend with care, e.g., to avoid making something public that is needed only by a tightly coupled class
  • Use const as much as possible.

File organisation

  • All header files should have #define guards
  • Make include files as independent of each other as possible, don’t use an include if forward declaration would suffice
  • Every header file must compile on its own
  • Sort and group #include s in a meaningful way
  • In general, put declarations in header files, definitions in source files
Last modified 7 years ago Last modified on 10/22/10 16:04:31