Overview of Google C++ Naming Style Guide

11/05/2021 Tags: C_C_plus_plus

Abstract

C++ language has many powerful features and is one of the main development languages used by many Google’s open-source projects. In addition, many projects are also developed by C++, such as A Simple C++ CSS Parser, Notepad++, … etc. Even though the language has many powerful features, but this power brings with it complexity which turn can make code more bug-prone and harder to read and maintain.

From my past work experiences, most of projects ussally follow its own project style guide for a large code repository. Here, I just wrote notes from C++ Style Guide from Google. The document is comprehensive and huge, so I am tring to study and overview ones that might be helpful for me to quickly recap the summary.

C++ style notes from Google C++ style guide

General Naming Rules

Naming Rules	Description
File Names	Prefer to use underscores(_) rather than dash(-).
Type Names	Start with a captial letter and have a capital letter for each new word, with no underscores: MyExcitingClass.
Variable Names	All lowercase with underscores between words.
Constant Names	Named with a leading "k" followed by mixed case. Underscores can be used as separators in the rare cases where capitalization cannot be used for separation: kDaysInAWeek.
Function Names	Ordinarily, functions should start with a capital letter and have a capital letter for each new word, but accessors and mutator may be named like variables.
Namespace Names	Top-level namespace names are based on the project name. namespace names all are lowercase, with words separated by underscores.
Enumerator Names	Should be named like constants, not like macros. That is, use kEnumName not ENUM_NAME.
Macro Names	Name macros with a project-specific prefic. Should be named with all capitials and underscores.

For more details, C++ style naming is available to read the most description on C++ naming style.

General Comments Rules

Comments Rules	Description
Comment Style	Use either the // or /* */, as long as you are consistent.
File Comments	Every file should contain license boilerplate. Choose the appropriate boilerplate for the license used by the project (for example, Apach 2.0, BSD ...).
Class Comments	Every non-obvious class or struct declaration should have an accompanying comment that describes what it is for and how it should be used.
Function Comments	Comments at the definition of a function of a function describe operation. Its definition should have an explanatory comment.
Variable Comments	In general the actual name of the variable should be descriptive enough to give a good idea of what the variable is used for.
Implementation Comments	Should have comments in tricky, non-obvious, interesting, or important parts of your code.

Note that: Do not state the obvious. In particular, don’t literally describe what code does, unless the behavior is nonobvuius to a reader who understands C++ well. Instead, provide higer level comments that describe why the code does what it does, or make the code self describing.

For more details, C++ style comments is available to read the most description on C++ comments style.

Conclution

The guide describes many of consistency since this property is more important than individual preferences. I also like consistency and feel that it is nice for the pattern-matching engine in our brain to deal on the naming rules. Here is also a talk from CppCon 2014: Titus Winters “The Philosophy of Google’s C++ Code” that one of the maintainers of doc give a talk on this topic. I particularly like that fact of starting off the purpose of a style guide.