Code Style Policy

There is a Git aliases file that provides the right commands to show and correct formatting errors. Add to your repository config by running this command from the source directory:

Then you can use the following aliases:

These aliases use a script, tools/check_coding.sh, which takes care of only checking the formatting for files that should be formatted. This script has other uses:

Class, typedef, enum, name space, and macro names should be comprised of all capital letters.

Examples

The first character of automatic, static local, and private variable names must be lower case. This indicates that the variable will not be “visible” outside of the function, file, or class where they are defined, respectively. The limited visibility is being acknowledged with the lowercase starting letter, where lowercase is considered to be less boisterous than uppercase.

Examples

Private class and struct members must be prefixed with m_ and the first character after the m_ prefix must also be lowercase:

The first character of public and global variable names must be uppercase. This indicates that the variable is visible outside the class or file in which it was defined. (An exception is the use of prefix g_ which is also sometimes used to indicate a global variable.)

Example

In general, classes should not use public member variables, and instead should use getter/setter methods to access private members. The exception is classes that are essentially data structures with some helper methods. For example, the SEG class is used frequently as a data structure representing a line segment between two points. This class has public member variables A and B storing those points. This is acceptable because the SEG class meets that definition of being essentially a data structure, and because there is no need for side-effects when changing A or B.

The first character of local, private, and static functions should be lower case. This indicates that the function is not visible outside the class or file where it is defined.

Example

Function arguments are prefixed with an 'a' to indicate these are arguments to a function. The 'a' stands for “argument”, and it also enables clever and concise Doxygen comments.

Example

Notice how the reader can say “a Foo” to himself when reading this.

It is not desired to identify a pointer by building a 'p' into the variable name. The pointer aspect of the variable pertains to type, not purpose.

Example

The purpose of the variable is that it represents a MODULE. Something like p_module would only make that harder to discern.

Use smart pointers where it makes sense to simplify memory management. Where using smart pointers, the STL types std::shared_ptr / std::unique_ptr are preferred. Do not use Boost smart pointers.

We do not use this→ to access either member variables or member functions from within the containing class. We let C++ perform this for us.

We do -not- use auto to reduce repetition. We do use it to increase readability. This generally means -only- use auto where std::lib gets overly verbose (such as iterators or std::make_shared), or when not using auto would cause line-wraps that can’t otherwise be avoided.

Example

In most circumstances, use of C-style casting is not permitted. Explicit C++-style casting should be used instead.

Example

If a comment is the first thing on a line, then that comment should have one or more blank lines above them. One blank line is preferred.

Doxygen is a C++ source code documenting tool used by the project. Descriptive *.html files can be generated from the source code by installing Doxygen and building the target named doxygen-docs.

The generated source *.html files will be placed into <kicad_project_base>/Documentation/doxygen/html/.

Doxygen comments are used to build developer documentation from the source code. They should normally be only placed in header files (.h) and not in source files (.cpp). This eliminates the obligation to keep two comments in agreement with each other. If the class, function, or enum, etc. is only defined in a source file and not present in any header file, in which case the Doxygen comments should go into the source file. Again, avoid duplicating the Doxygen comments in both the header and source files.

KiCad uses the JAVADOC comment style defined in the doccode section of the Doxygen manual. Don’t forget to use the special Doxygen tags : bug, todo, deprecated, etc., so other developers can quickly get useful information about your code. It is good practice to actually generate the Doxygen *.html files by building target doxygen-docs, and then to review the quality of your Doxygen comments with a web browser before submitting a patch.

Avoid defining class and function names and argument and return data types. This redundant information can easily be read by other developers and shows up as redundant information in the generated documentation.

Use Doxygen’s markdown syntax where possible instead of HTML tags. Markdown makes for more readable comments than mark up languages.

Use Doxygen links when referring to other code in Doxygen comments. This makes information easier to find for other developers.

Group related sections of comments together as much as possible using the Doxygen grouping commands. This makes finding related information easier than having it spread across multiple document pages.

The indentation level for the KiCad source code is defined as four spaces. Please do not use tabs.

The maximum line width is 99 columns. An exception to this is a long quoted string such as the internationalized text required to satisfy MSVC++, described below.

The KiCad project team no longer supports compiling with Microsoft Visual C++. When you need to break long strings into smaller substrings, please use the C99 compliant method for improved readability. Using any of previously accepted methods defined below for breaking long internationalized strings will no longer be accepted.

Examples

A second acceptable solution is to simply put the text all on one line, even if it exceeds the 99 character line length limit. However, the preferred method is to break strings within the 99 character limit whenever possible to prevent wrapping.

When line breaking expressions the operators should appear at the beginning of a line, not at the end.

Many programming editors conveniently indent your code for you. Some of them do it rather poorly and leave trailing whitespace. Thankfully, most editors come with a remove trailing whitespace macro or at least a setting to make trailing whitespace visible so you can see it and manually remove it. Trailing whitespace is known to break some text parsing tools. It also leads to unnecessary diffs in the version control system. Please remove trailing whitespace.

It is generally preferred that each statement be placed on its own line. This is especially true for statements without keywords.

Braces should be placed on the line proceeding the keyword and indented to the same level. It is not necessary to use braces if there is only a single line statement after the keyword. In the case of if..else if..else, indent all to the same level.

Braces are required if the control statement spans more than one line, even if the control block is a single line. This makes it easier to visually parse.

Parenthesis should be placed immediately after function names and keywords. Spaces should be placed after the opening parenthesis, before the closing parenthesis, and between the comma and the next argument in functions. No space is needed if a function has no arguments.

The case statement is to be indented to the same level as the switch.

It is preferred to place all cases on a single line when that makes the code more readable. This is often done for look-ups or mapping functions. In this case, you will have to manually align for readability as appropriate and reject clang-format’s suggested changes, if you use it:

The braces and statements of the body should be indented as you would a method, with the braces lined up under the capture block:

or:

When defining classes, member variables should be placed at the bottom and methods should be placed above the member variables. The scope ordering of the class should be public, protect, then private. Do not redefine the same scope multiple times in a row. Here is an example class definition:

Class methods used to read and write from private class members without any other side effects are permitted to violate several of the normal formatting rules in order to improve legibility. These methods can exist all on one line, with no blank line between:

There are occasions when you want to see debugging output to ensure existing code performs as expected. In this case, use wxLogTrace which allows debugging output to be controlled by the WXTRACE environment variable. When using wxLogTrace, the trace environment variable string should be documented by either adding it to the trace_helper.{h/cpp} source files or locally using the Doxygen comment \ingroup trace_env_vars. To prevent WXTRACE name space conflicts, all trace variable strings should be prefixed with "KICAD_".

Each header file should include an #ifndef which is commonly used to prevent compiler errors in the case where the header file is seen multiple times in the code stream presented to the compiler. Just after the license statement, at the top of the file there should be lines similar to these (but with a file name specific token other than RICHIO_H_):

And at the very bottom of the header file, use a line like this one:

The #ifndef wrapper begins after the license statement, and ends at the very bottom of the file. It is important that it wrap any nested #include statements, so that the compiler can skip them if the #ifndef evaluates to false, which will reduce compilation time.

Any header file should include other headers that it depends on. (Note: KiCad is not at this point now, but this section is a goal of the project.)

It should be possible to run the compiler on any header file within the project, and with proper include paths being passed to the compiler, the header file should compile without error.

Example

Such structuring of the header files removes the need within a client *.cpp file to include some project header file before some other project header file. (A client *.cpp file is one that intends to use, not implement, the public API exposed within the header file.)

Client code should not have to piece together things that a header file wishes to expose. The exposing header file should be viewed as a fully sufficient ticket to use the public API of that header file.

This is not saying anything about how much to expose, only that that which is exposed needs to be fully usable merely by including the header file that exposes it, with no additional includes.

For situations where there is a class header file and an implementation *.cpp file, it is desirable to hide as much of the private implementation as is practical and any header file that is not needed as part of the public API can and should be included only in the implementation *.cpp file. However, the number one concern of this section is that client (using) code can use the public API which is exposed in the header file, merely by including that one header file.