C Example

example.h

/**
 * @file example.h
 * This is an example header file.
 *
 * The description of the file's purpose goes here, starting at one blank
 * line after the name.
 */


// ALL header files should contain an include guard
// The name of the defined variable should be the name of the file in all
// caps with spaces and periods replaced with underscores
#ifndef EXAMPLE_H
#define EXAMPLE_H


// Includes go inside the include guard
#include <stdint.h>


/**
 * @define EXAMPLE_DEFINE_SIX
 * Brief description of EXAMPLE_DEFINE (contains 6).
 * Defines should be all caps, and go inside the include guard unless
 * absolutely necessary.
 */
#define EXAMPLE_DEFINE_SIX 6


/**
 * @struct this_is_a_struct_t
 * Brief description of this_is_a_struct_t
 */
struct this_is_a_struct_t
{
    uint32_t someStructElement;         /**< Attributes use camelCase */
    uint32_t anotherStructElement;      /**< Example of an inline element */

    /**
     * This member documentation isn't inline.
     * This allows space to give a very detailed description of what it's for.
     */
    uint32_t someOtherStructElement[32];
}


/**
 * @typedef EXAMPLE_TYPE
 * Example typedef.
 * Typedefs should use all caps with underscores
 */
typedef struct this_is_a_struct_t EXAMPLE_TYPE;


// ----------------------------------------------------------------------------
//
// Use dividers like this to separate sections if you want to be super extra
//
// ----------------------------------------------------------------------------


/**
 * This is an example function.
 * These function headers are mandatory. Everyone will hate you if you leave
 * this out, since they'll have no idea what you just did. Yes, if you skip
 * this, you should feel bad.
 *
 * @param exampleInput example input value; does nothing
 * @param uselessInt also does absolutely nothing.
 * @return
 *      Packed uint16_t object;
 *      | 6 in ascii (8 bits) | 6 in binary |.
 *      This section can be omitted if the return is self explanatory or is
 *      a void type.
 */
uint16_t exampleFunction(EXAMPLE_TYPE exampleInput, uint32_t uselessInt);


/**
 * Brief description of ExampleClass.
 */
class ExampleClass
{
    public:

        /** Contains the number 6 */
        uint16_t theNumberSix;

        /**
         * Example Method
         * Header for the method ExampleClass::exampleMethod; this header is
         * the same as an ordinary function header.
         *
         * @param number number to set exampleMember to.
         */
        void exampleMethod(uint16_t number);

    private:

        /** Contains a number set by exampleMethod */
        uint16_t exampleMember;
}

#endif

// | | Make sure the file ends with a blank line | |
// v v                                           v v

example.cpp

/**
 * @file example.cpp
 * This is an example C++ file.
 *
 * The description of the file's purpose goes here, starting at one blank
 * line after the name.
 */

// Optional line[s] to describe includes
// Header file with struct definitions
#include "example.h"


// Function header copied from header file
/**
 * This is an example function.
 * These function headers are mandatory. Everyone will hate you if you leave
 * this out, since they'll have no idea what you just did. Yes, if you skip
 * this, you should feel bad.
 *
 * @param exampleInput example input value; does nothing
 * @param uselessInt also does absolutely nothing.
 * @return
 *      Packed uint16_t object;
 *      | 6 in ascii (8 bits) | 6 in binary |.
 *      This section can be omitted if the return is self explanatory or is
 *      a void type.
 */
uint16_t exampleFunction(EXAMPLE_TYPE exampleInput, uint32_t uselessInt)
{
    uint16_t six = EXAMPLE_DEFINE_SIX;
    uint8_t eight;

    // Multiline statements should contain line breaks after arithmetic
    // operators with indentation levels matching
    eight = six + six - six + six - six + six -
            six + six - six + six - six + six -
            six + six - six + six - six + 2;

    if(1 < 0)
    {
        // Don't actually use these names
        EXAMPLE_TYPE randomStructWithVeryLongName;
        uint32_t randomIntegerWithExtremelyVeryLongNameForNoGoodReason;

        // Function arguments can start on new lines at a new indentation level
        // If they are too long to fit on one line
        exampleFunction(
            randomStructWithVeryLongName,
            randomIntegerWithExtremelyVeryLongNameForNoGoodReason,
        );

        // Or the first argument can start on the same line, with subsequent
        // arguments starting at the same column as the first argument
        exampleFunction(randomStructWithVeryLongName,
                        randomIntegerWithExtremelyVeryLongNameForNoGoodReason);
    }

    // Multiline if statements should contain newlines after logical operators
    // This is where putting the { on its own line comes in handy
    if((eight < six) || (eight * eight < six * six) ||
       (eight + eight * six < eight + six * six))
    {
        eight++;
    }

    // Don't include redundant parentheses in return statements
    return (uint16_t) '6' << eight | six;
}


/**
 * Example Method
 * Header for the method ExampleClass::exampleMethod; this header is
 * the same as an ordinary function header.
 *
 * @param number number to set exampleMember to.
 */
void ExampleClass::exampleMethod (uint16_t number)
{
    exampleMember = number;
}

// | | Make sure the file ends with a blank line | |
// v v                                           v v