KiCad PCB EDA Suite
Latest Publishing: February 2013
First Published: September 2010
Wayne Stambaugh <email@example.com@firstname.lastname@example.org@m.izon.nosp@m..net> and Dick Hollenbeck <dick@.email@example.com@firstname.lastname@example.org>
The purpose of this document is to provide a reference guide for KiCad developers about how source code should be styled and formatted in KiCad. It is not a comprehensive programming guide because it does not discuss many things such as software engineering strategies, source directories, existing classes, or how to internationalize text. The goal is to make all of the KiCad source conform to this guide.
You may be thinking to yourself that using the style defined in this document will not make you a good programmer and you would be correct. Any given coding style is no substitute for experience. However, any experienced coder will tell that the only thing worse than looking at code that is not in your preferred coding style, is looking at twenty different coding styles that are not your preferred coding style. Consistency makes a) problems easier to spot, and b) looking at code for long periods of time more tolerable.
The KiCad coding police are not going to break down your door and beat you with your keyboard if you don't follow these guidelines (although there are those who would argue that they should). However, there are some very sound reasons why you should follow them. If you are contributing patches, you are much more likely to be taken seriously by the primary developers if your patches are formatted correctly. Busy developers don't have the time to go back and reformat your code. If you have a desire to become a regular KiCad developer with commit access to the development branch, you're not likely to get a glowing recommendation by the lead developers if you will not follow these guidelines. It is just good programming courtesy to follow this policy because it is respectful of the investment already made by the existing developers. The other KiCad developers will appreciate your effort.
Do not modify this document without the consent of the project leader. All changes to this document require approval.
Before delving into anything as esoteric as indentation and formatting, naming conventions need to be addressed. This section does not attempt to define what names you use for your code. Rather, it defines the style for naming. See the references section for links to some excellent coding references. When defining multiple word names use the following conventions for improved readability:
Avoid mixing camel case and underscores.
Class, typedef, enum, name space, and macro names should be comprised of all capital letters.
The first character of automatic, static local, and private variable names should 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.
The first character of public and global variable names are to 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.)
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.
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.
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.
The purpose of the variable is that it represents a MODULE. Something like
p_module would only make that harder to discern.
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.
Comments in KiCad typically fall into two categories: in line code comments and Doxygen comments. In line comments have no set formatting rules other than they should have the same indent level as the code if they do not follow a statement. In line comments that follow statements should not exceed 99 columns unless absolutely necessary. The prevents word wrapping in an editor when the viewable columns is set to 100. In line comments can use either the C++ or the C commenting style, but C++ comments are preferred for single line comments or comments consisting of only a few lines.
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.
$ cd <kicad_build_base> $ make doxygen-docs
The *.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 and not in *.cpp files. This eliminates the obligation to keep two comments in agreement with each other. is if the class, function, or enum, etc. is only defined in a *.cpp source file and not present in any header file, in which case the Doxygen comments should go into the *.cpp source file. Again, avoid duplicating the Doxygen comments in both the header and *.cpp source files.
KiCad uses the JAVADOC comment style defined in the “Documenting the code” 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.
These go into a header file, unless the function is a private (i.e. static) function known only to a *.cpp file. The format of a function comment is chosen to serve a dual purpose role: delineation of the function declaration within the source code and to create a consistent leading sentence in the doxygen html output. The chosen format is “Function <name>” as shown in the example below.
The “Function <name>” text goes on the 2nd line of the comment. The @return keyword if present, should show the type of the return value followed by a hiphen. The @param keyword names a function parameter and the text following should flow like a normal English sentence.
A class comment describes a class declaration by giving the purpose and use of the class. Its format is similar to a function comment. Doxygen can use the html <p> (paragraph designation) to begin a new paragraph in its output. So if the text of the comment is large, break it put into multiple paragraphs.
This section defines the formatting style used in the KiCad source.
The indentation level for the KiCad source code is defined as four spaces. Please do not use tabs.
There should be only one space after a #define statement.
Please try to align multiple consecutive similar lines into consistent columns when possible, such as #define lines which can be thought of as containing 4 columns: #define, symbol, value, and comment. Notice how all 4 columns are aligned in the example below.
Another common case is the declaration of automatic variables. These are preferably shown in columns of type and variable name.
There should be 1 blank line above a function declaration in a class file if that function declaration is presented with a Javadoc comment. This is consist with the statement above about blank lines above comments.
Function definitions in *.cpp files will not typically be accompanied by any comment, since those are normally only in the header file. It is desirable to set off the function definition within the *.cpp file by leaving two blank lines above the function definition.
There should be one blank line above if statements.
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.
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.
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.
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.
There is a the file copyright.h which you can copy into the top of your new source files and edit the <author> field. KiCad depends on the copyright enforcement capabilities of copyright law, and this means that source files must be copyrighted and not be released into the public domain. Each source file has one or more owners.
Project *.h source files should:
The license statement was described above.
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 filename specific token other than
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.
$ cd /svn/kicad/testing.checkout/include $ g++ wx-config --cxxflags -I . xnode.h -o /tmp/junk
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.
It's OK. We all make mistakes. Fortunately, KiCad provides a configuration file for the code beautifier uncrustify. Uncrustify won't fix your naming problems but it does a pretty decent job of formatting your source code. There are a few places where uncrustify makes some less than ideal indentation choices. It struggles with the string declaration macros wxT(“”) and _(“”) and functions used as arguments to other functions. After you uncrustify your source code, please review the indentation for any glaring errors and manually fix them. See the uncrustify website for more information.
Nothing drives the point home like an example. The source file richio.h below was taken directly from the KiCad source.
There are plenty of excellent resources on the Internet on C++ coding styles and coding do's and don'ts. Here are a few useful ones. In most cases, the coding styles do not follow the KiCad coding style but there is plenty of other good information here. Besides, most of them have some great humor in them enjoyable to read. Who knows, you might even learn something new.