Hugin Coding Style Guide

Consistent application of a style makes life easier for everybody. You'll find other people's code more readable, and they will find your code more readable. While nobody will tap on your fingers for not following these conventions to the letter, it is highly recommended that you familiarize with them and follow them.

History and Status of this Document

This document started from a discussion on coding style and consistency. It is currently just a collection of the wisdom and opinion of Hugin contributors and we won't do hard enforcement / policing, but it would be nice if we could all stick to the same convention and make the code more readable and manageable for everyobdy.

Naming Conventions

Contraction Lists

The list is incomplete.

Metadata

Documentation

Document your code (or the code you are reading and understanding) with doxygen. Doxygen is a useful tool and can also be used to create other documentation that just class interface descriptions. It works by prefixing the function prototypes with a special comment. Pablo usually puts the documentation in the header files.

The basic usage is very javadoc like:

/** One sentence class description
 *
 *  more detailed description
 *
 *  @todo pet the cat more often
 *  @bug  might scratch if annoyed
 */
class Cat
{
public:
    /** hunt food
     *
     *  @param prey type of animals that we should hunt
     *  @return true if the cat is sated
     */
    bool HuntFood(Prey prey);

}

Identify Work in Progress

Comments

Comments and inline-documentation are always welcome, please give them lines of their own and don't append them to existing code:

exit(); do_stuff(); //Don't do this

File Names

Try to keep one class per file, and give the file a meaningful name in CamelCase.

Code Layout

Spacing and indentation contirbute a lot to the readability of the code. Use them liberally.

Bracing

There are many different indentation styles. Allman style is the preferred one. However it is more important to keep consistency within a file, so if you are editing a file with a different convention, adopt it (or read the clean up section of this style guide).

if (1 == 0)
{
    printf("never");
} 
else
{
    printf("ever");
}

Tabulation

Use spaces instead of tabulators (to maintain consistency across editors). The preferred indentation is four spaces for one tab, but most important is to keep consistency within a single file.

Spacing

I would not go into that much detail. or maybe we should adopt/adapt a strict coding guide like Blender?

Line Ends

Set your editor to Unix-style line ending (LF) - not Windows' LF+CR. Or if you are on Windows, use the Mercurial EOL extension.

To prevent accidentally committing a file with Windows line endings, you can add the following snippet to your global .hgrc or mercurial.ini file:

[hooks]
pretxncommit.crlf = python:hgext.win32text.forbidcrlf

Character Set

Ideally we are striving to use UTF-8, but because Windows has issue dealing with it, the wxWidgets XRC ressources are ISO-8859-1.

Multiple Statements on one Line

Avoid multiple statements on one line, it makes the code harder to read.

Line Width

Try to keep line width below 80 characters.

Repository

Commits

It is tempting to clean up old code while fixing bugs or adding new code. Please don't - it makes the committ (diff!) much more difficult to read / understand. Keep style clean up committs separated and mention them as such in the log message.

It is important that nobody goes around changing existing code to suit without thinking about it first - We have several branches waiting to be merged, changing the amount of whitespace makes that difficult, and splitting or joining lines of code makes it enormously more so.

Work in Progress

If something needs work, mark it with a // FIXME or // TODO comment so that a grep will reveal places that needs attention. Gedit automatically highlights TODO and FIXME.

For minor changes, feel free to commit directly into the default codeline. For everything else, branch out. Branches are cheap.

Strings for Translation

Release branches are string-frozen. Strings for translation are updated prior to branching and in principle no new string shall be added to a release branch. An exception may be requested if the underlying motive is important enough. The request must receive the support of a significant majority of developers (coders, builders, translators) to be granted. Silence is interpreted as supportive of the request.

API stability

Release branches are frozen regarding classes/function/namespace names and functions parameters. An exception may be requested if the underlying motive is important enough. The request must receive the support of a significant majority of developers (coders and scripters) to be granted. Silence is interpreted as supportive of the request.

License

/*
** <one line to give the program's name and a brief idea of what it does.>
** Copyright (C) <year>  <name of author>
**
** This program is free software: you can redistribute it and/or modify
** it under the terms of the GNU General Public License as published by
** the Free Software Foundation, either version 2 of the License, or
** (at your option) any later version.
**
** This program is distributed in the hope that it will be useful,
** but WITHOUT ANY WARRANTY; without even the implied warranty of
** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
** GNU General Public License for more details.
**
** You should have received a copy of the GNU General Public License
** along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

Goto / Case Labels

Try to write code that is linear to read and does not jump all over the place too much.

Compilation Warnings and Diagnostic Output

Try to prevent compiler warnings.

Encapsulate diagnostic output in a condition and commit it so that by default there is no diagnostic output. Consider that some CMake output must be clicked away on Windows while it is just an extra line of display in Linux.

 

Return to main page.