IGVC Coding Conventions

From GT RoboJackets

The following coding standard are strongly recommended for any code that goes into the official IGVC codebase. Historically, code style was not standardized - and thus you may run into legacy code that does not conform to these standards.

Contents 1 Coding Effort 2 Editor Settings 3 C++ Coding Conventions 3.1 Package (Directory) Names 3.2 File Names 3.3 Identifiers 3.4 Inclusion Guards 4 C Coding Conventions 5 Documentation Comments

Coding Effort

Coding effort should be allocated so that the resultant product is:

1. correct
   • if it doesn't work, it's useless
2. readable
   • code should be quickly modifiable at the competition when things go wrong
   • code should be modifiable by people other than the author
3. fast
   • fast is good

(in that order)

Editor Settings

• 4 spaces per tab
• use tabs (not spaces) for indentation

C++ Coding Conventions

The C++ coding conventions specified here are similar to the Sun's set of coding conventions for Java.

Code in C++ should use prefer the use of classes over structs as much as possible.

Package (Directory) Names

Package names should be in all lowercase and preferably be single words. Well-known acronyms (such as io or util) are also suitable as package names. In the interest of keeping package names as short as possible, reasonable abbreviations in the words that comprise a package name are permitted.

• packagename
• io (input/output)
• hw (hardware)

File Names

• ClassName.cc
  • NOTE: The preferred file extension is somewhat arbitrary.
• ClassName.h
• EnumName.h
• typedefNames.h (rare)

Identifiers

• ClassName
• EnumName
• methodName
• fieldName
• localVariableName
• CONSTANT_NAME
• ENUM_CONSTANT
  • Most enum constants should be prefixed with an acronymized form of their enum type name.
    • For example, constants of the JMessageType enum type should be prefixed with JMT_.
    • Neither C++ nor C creates separate namespaces for enum constants. Therefore prefixing is necessary to avoid name collisions between same-named constants of different enum types.
• T (generic type parameter name)
  • Type parameters should be single capital letters.
  • The letter used should logically correspond to the role of the type.
    • E for element-type.
    • K for the key-type of a map.
    • V for the value-type of a map.

Inclusion Guards

All header files should have inclusion guards to allow them to be included multiple times without the C preprocessor having a fit.

For a file named ClassName.h, the inclusion guards should look like:

#ifndef CLASS_NAME_H
#define CLASS_NAME_H

...

#endif

C Coding Conventions

TODO: ...

Documentation Comments

Javadoc-style Doxygen-compliant documentation comments should be used.

It is strongly recommended that all classes and public methods be documented. Documentation comments for classes and public methods should appear in the header file (not in the source file).

It is not specified where documentation comments for private methods should be located.

Here are some examples:

/**
 * Utility class that represents a resizable 2D matrix of elements.
 * 
 * @param E             the type of element in the buffer.
 */
template<typename E>
class Buffer2D {
private:
    E* data;
    int width;
    int height;
    
    // ### INIT ###
public:
    /** Creates a new buffer of size (0,0). */
    Buffer2D<E>();
    /**
     * Creates a new buffer with the specified size.
     * 
     * @param width     the width of the buffer to create.
     * @param height    the height of the buffer to create.
     */
    Buffer2D<E>(int width, int height);

    // no need to document destructors
    ~Buffer2D<E>();

    // ### ACCESSORS ###
public:
    /**
     * @param x         the x location of the element to return.
     * @param y         the y location of the element to return.
     * @return          the element at the specified (x,y) position.
     */
    E get(int x, int y);

    // ### OPERATIONS ###
public:
    /**
     * Resizes this buffer (if the specified new size is different than the old size).
     * If <tt>width</tt> or <tt>height</tt> is 0, then no new buffer will be allocated.
     * If the resize is successful and a new buffer is allocated,
     * the contents of the new buffer are undefined.
     * 
     * @param width     the new width of this buffer.
     * @param height    the new height of this buffer.
     * @return          whether this buffer was resized successfully.
     */
    bool resize(int width, int height);
};

/**
 * Hash table based implementation of a {@link Map}.
 * 
 * @param K             the key-type of the map.
 * @param V             the value-type of the map.
 */
template<typename K, typename V>
class HashMap : public Map<K,V> {
    ...
}