VisiLibity Coding Standards

• 80 character line width
• be liberal with whitespace to aid readablility

• use descriptive identifiers
• make use of prefixes such as is_, get_, set_ and suffixes _max, _cnt, _key
• never use a leading underscore because compiler variables do
• private and protected member data identifiers are all lowercase with a single underscore suffix, e.g, x_
• use ALL_UPPERCASE for identifiers of #defined constants, macros, and values of enum type
• use First_Letter_Upper_Case for identifiers of namespaces and user defined types, such as classes (extra uppercase letters can be used for exceptional special words like VisiLibity, but never use all uppercase for an abbreviation, even acroyms)
• use all_lowercase for identifiers of local variables, functions, and formal parameters
• prefix global variables with g_ and static variables with s_

• document in the source code using Doxygen
  • for brief description only, use the C++ style triple slash, e.g.,

          /// a brief description
          

  • for descriptions beyond just brief, use the JavaDoc style, which consists of a C-style comment block starting with two *s, e.g.,

          /** \brief first part of brief desicription
           *         brief description continued
           *
           * longer description, details, if you like...
           * \author  your name
           * \param x  description of \a x
           * \pre  a precondition
           * \post  a postcondition
           * \remarks  some remarks, e.g., time complexity O(n^2)
           * \return  a number
           */
          

  • documentation blocks should be placed immediately before the item they are describing, otherwise additional syntax required
  • JAVADOC_AUTOBRIEF is set to NO, so you must use the \brief directive
  • feel free to make notes using commands such as \todo{} and \warning{}
  • sign your work with the \author field whenever a method is sufficiently complicated that it takes you more than a few minutes to write