Layout | C Plus Plus Standards

Summary

Define how to layout code, how to use certain syntax and generally how code looks more than how code functions.

1. Public Classes, Methods, Variables and Accessible attributes should be commented.

Where there is any ambiguity at all, public attributes found within the engine should be commented. This means that classes, methods, properties, structs, enums and the values contained should all be considered for comments.

1. Example

// Maybe ambigous?
class Race
{
    // What lap is this? There would be many cars... is this the number of laps?
    int Lap;
}

/// <summary>
/// Defines a single race within the given session
// </summary>
class Race
{
    /// <summary>
    /// The lap the person in front is on
    /// </summary>
    int Lap;
}

1. Reason

Our code is going to grow large and is to be used by many people. We should attempt to help them by leaving breadcrumbs of knowledge to the truth of our code.

2. Context braces own their own line.

When defining a new context using { } braces, these should always go on a new line.

2. Example

void MyMethod()
{
    if(File::Exists("some path"))
    {
        Logger::Error("Does not exist");
        return;
    }
    
    // Do stuff
}

2. Reason

It should be clear what context you are in at any given time.

3. Code lines should not take up too much space - keep it short!

When writing lines of code, they should not trail off into the right side of the screen such that scrolling to the right becomes the norm. Use method level stack variables to shorten the names, or break the line where needed to keep it short!

3. Example

// Do Not
class Example
{
    std::string myString = "This, is my cool string, I am going to walk off the end of the screen and if this were on the actual screen you would need to scroll right.";
}

// Do
class Example
{
    std::string myString = "This, is my cool string, I am going to walk off the end of the " +
                            "screen and if this were on the actual screen you would need to " + 
                            "scroll right.";
}

3. Reason

Long lines are more difficult to comprehend. Additionally, the detail in lines tends to be on the right side, therefore you want this detail to be seen not hidden.

4. Public first in headers

Always start a new object with public.

4. Example

class Example
{
public:
    void Set(int x);
    int Get(x) const;
private:
    int m_x;
}

4. Reason

The Public facing behaviour of a Class is the most important. Sell it first.

Last modified: 04 April 2024