Important: Make sure you use the visual studio formatter from VS2019 or later!
This document describes the coding style used for C/C++ code in TheTomcatProject. All code should conform to this style.
We'll definitely be tweaking and amending this over time, so let's consider it a living document. :)
A combination of CamelCase and snake_case. Use CamelCase (Capitalize the first letter, including all letters in an acronym) in a class, struct, or namespace name. Use snake_case (all lowercase, with underscores separating words) for variable and function names.
struct Entry;
size_t buffer_size;
class FileDescriptor;
String absolute_path();struct data;
size_t bufferSize;
class Filedescriptor;
String MIME_Type();Use full words, except in the rare case where an abbreviation would be more canonical and easier to understand.
size_t character_size;
size_t length;
short tab_index; // More canonical.size_t char_size;
size_t len;
short tabulation_index; // Goofy.Data members in C++ classes should be private. Static data members should be prefixed by "s_". Other data members should be prefixed by "m_". Global variables should be prefixed by "g_".
class String {
public:
...
private:
int m_length { 0 };
};class String {
public:
...
int length { 0 };
};Precede setters with the word "set". Use bare words for getters. Setter and getter names should match the names of the variables being set/gotten.
void set_count(int); // Sets m_count.
int count() const; // Returns m_count.void set_count(int); // Sets m_the_count.
int get_count() const; // Returns m_the_count.Precede getters that return values through out arguments with the word "get".
void get_filename_and_inode_id(String&, InodeIdentifier&) const;void filename_and_inode_id(String&, InodeIdentifier&) const;Use descriptive verbs in function names.
bool convert_to_ascii(short*, size_t);bool to_ascii(short*, size_t);When there are two getters for a variable, and one of them automatically makes sure the requested object is instantiated, prefix that getter function with ensure_. As it ensures that an object is created, it should consequently also return a reference, not a pointer.
Inode* inode();
Inode& ensure_inode();Inode& inode();
Inode* ensure_inode();When a function raises an exception, prefix with try_. As it tries, you can surround it with a try/catch to catch any error from that function.
unsigned int try_altitude();unsigned int altitude();Leave meaningless variable names out of function declarations. A good rule of thumb is if the parameter type name contains the parameter name (without trailing numbers or pluralization), then the parameter name isn't needed. Usually, there should be a parameter name for bools, strings, and numerical types.
void set_count(int);
void do_something(Context*);void set_count(int count);
void do_something(Context* context);Prefer enums to bools on function parameters if callers are likely to be passing constants, since named constants are easier to read at the call site. An exception to this rule is a setter function, where the name of the function already makes clear what the boolean is.
do_something(something, AllowFooBar::Yes);
paint_text_with_shadows(context, ..., text_stroke_width > 0, is_horizontal());
set_resizable(false);do_something(something, false);
set_resizable(NotResizable);Enum members should use InterCaps with an initial capital letter.
Prefer const to #define. Prefer inline functions to macros.
#defined constants should use all uppercase names with words separated by underscores.
Use #pragma once instead of #define and #ifdef for header guards.
// MyClass.h
#pragma once// MyClass.h
#ifndef MyClass_h
#define MyClass_hConstructors for C++ classes should initialize their members using C++ initializer syntax. Each member (and superclass) should be indented on a separate line, with the colon or comma preceding the member on that line. Prefer initialization at member definition whenever possible.
class MyClass {
...
Document* m_document { nullptr };
int m_my_member { 0 };
};
MyClass::MyClass(Document* document)
: MySuperClass()
, m_document(document)
{
}
MyOtherClass::MyOtherClass()
: MySuperClass()
{
}MyClass::MyClass(Document* document) : MySuperClass()
{
m_myMember = 0;
m_document = document;
}
MyClass::MyClass(Document* document) : MySuperClass()
: m_my_member(0) // This should be in the header.
{
m_document = document;
}
MyOtherClass::MyOtherClass() : MySuperClass() {}Prefer index or range-for over iterators in Vector iterations for terse, easier-to-read code.
for (auto& child : children)
child->do_child_thing();for (int i = 0; i < children.size(); ++i)
children[i]->do_child_thing();for (auto it = children.begin(); it != children.end(); ++it)
(*it)->do_child_thing();Both pointer types and reference types should be written with no space between the type name and the * or &.
An out argument of a function should be passed by reference except rare cases where it is optional in which case it should be passed by pointer.
void MyClass::get_some_value(OutArgumentType& out_argument) const
{
out_argument = m_value;
}
void MyClass::do_something(OutArgumentType* out_argument) const
{
do_the_thing();
if (out_argument)
*out_argument = m_value;
}void MyClass::get_some_value(OutArgumentType* outArgument) const
{
*out_argument = m_value;
}using statements are NOT acceptable. It can only be considered for the test framework.
In C++ implementation files, do not use "using" declarations of any kind to import names in the standard template library. Directly qualify the names at the point they're used instead.
Do not omit "int" when using "unsigned" modifier. Do not use "signed" modifier. Use "int" by itself instead.
unsigned int a;
int b;unsigned a; // Omit "int".
signed b; // Uses "signed" instead of "int".
signed int c; // Doesn't omit "signed".For types with methods, prefer class over struct.
- For classes, make public getters and setters, keep members private with
m_prefix. - For structs, let everything be public and skip the
m_prefix.
struct Thingy {
String name;
int frob_count { 0 };
};
class Doohickey {
public:
String const& name() const { return m_name; }
int frob_count() const { return m_frob_count; }
void jam();
private:
String m_name;
int m_frob_count { 0 };
}struct Thingy {
public:
String m_name;
int frob_count() const { return m_frob_count; }
private:
int m_frob_count { 0 };
}
class Doohickey {
public:
String const& name() const { return this->name; }
void jam();
String name;
int frob_count { 0 };
};Use a static member function named "the()" to access the instance of the singleton.
class UniqueObject {
public:
static UniqueObject& the();
...class UniqueObject {
public:
static UniqueObject& shared();
...class UniqueObject {
...
};
UniqueObject& my_unique_object(); // Free function.Make comments look like sentences by starting with a capital letter and ending with a period (punctuation). One exception may be end of line comments like this if (x == y) // false for NaN.
Use FIXME: (without attribution) to denote items that need to be addressed in the future.
draw_jpg(); // FIXME: Make this code handle jpg in addition to the png support.draw_jpg(); // FIXME(joe): Make this code handle jpg in addition to the png support.draw_jpg(); // TODO: Make this code handle jpg in addition to the png support.Explain why the code does something. The code itself should already say what is happening.
i++; // Go to the next page.// Let users toggle the advice functionality by clicking on catdog.
catdog_widget.on_click = [&] {
if (advice_timer->is_active())
advice_timer->stop();
else
advice_timer->start();
};page_index++;i++; // Increment i.// If the user clicks, toggle the timer state.
catdog_widget.on_click = [&] {
if (advice_timer->is_active())
advice_timer->stop();
else
advice_timer->start();
};The declaration of a virtual method inside a class must be declared with the virtual keyword. All subclasses of that class must either specify the override keyword when overriding the virtual method or the final keyword when overriding the virtual method and requiring that no further subclasses can override it.
class Person {
public:
virtual String description() { ... };
}
class Student : public Person {
public:
virtual String description() override { ... }; // This is correct because it only contains the "override" keyword to indicate that the method is overridden.
}
class Person {
public:
virtual String description() { ... };
}
class Student : public Person {
public:
virtual String description() final { ... }; // This is correct because it only contains the "final" keyword to indicate that the method is overridden and that no subclasses of "Student" can override "description".
}
class Person {
public:
virtual String description() { ... };
}
class Student : public Person {
public:
String description() override { ... }; // This is incorrect because it uses only the "override" keywords to indicate that the method is virtual. Instead, it should use both the "virtual" and "override" keywords.
}class Person {
public:
virtual String description() { ... };
}
class Student : public Person {
public:
String description() final { ... }; // This is incorrect because it uses only the "final" keywords to indicate that the method is virtual and final. Instead, it should use both the "virtual" and "final" keywords.
}class Person {
public:
virtual String description() { ... };
}
class Student : public Person {
public:
virtual String description() { ... }; // This is incorrect because it uses the "virtual" keyword to indicate that the method is overridden.
}Use style where const is written on the left side of the type being qualified.
const Salt& m_salt;Salt const& m_salt;Use const, constexpr, constval anywhere you can.