Suivez nous sur :

Accueil » Développeurs » Style du code source

Style du code d'Inkscape

Cette page documente les conventions utilisées dans le code source d'Inkscape. Veuillez suivre ces conventions lorsque vous écrivez du nouveau code. Si vous voyez du code qui ne s'y conforme pas, sentez-vous libre de le corriger !

sLes bases : retraits, espaces et accolades

Le code est systématiquement mis en retrait avec quatre quatre espaces. Les caractères de tabulation ne sont pas autorisé à quelque endroit que ce soit dans les fichiers. La seule exception est dans les fichiers de compilation système et makefiles dont la syntaxe impose des caractères de tabulation.

Les choses suivantes sont mises en retrait :

Les choses suivantes ne sont pas mise en retrait :

Code is written using compact braces, which means that the opening brace goes on the same line as the control statement. The closing brace of an if block goes on the same line as the following else keyword. However, there is an exception: if the condition of an if or while or the header of a for loop are broken into more than one line, the opening brace goes on a separate line. Braces are mandatory and must not be omitted even when the body of the block has only a single line. For function definitions, the opening brace should go on a separate line if the function is more than a few lines long or when the argument list spans more than a single line. Opening braces of constructors with member initializers must go on a separate line.

Spaces are present in the following places:

Spaces are absent in the following places:

Member initializer lists and base class lists that contain more than one class should be written using Boost-style indentation: each member or class goes on a separate line and is preceded by the appropriate punctuation and a space. This makes it very easy to spot errors.

namespace Inkscape {
namespace UI {

Sandwich make_sandwich(int x);
int make_a_mess(float y);

} // namespace UI
} // namespace Inkscape

class Bunkum
    : public Nonsense
    , protected PublicSpeech
{
public:
    Bunkum()
        : _x(1024)
        , _y(42)
    {}
private:
    void _forget();
    int _x, _y;
};

template <typename Basket>
void fill_basket(Basket &b)
{
    switch (a) {
    case 1:
        do_one();
        break;

    case 2:
        do_two();
        break;

    default:
        break;
    }

    for (int i = 0; i < 30; ++i) {
        b << Inkscape::UI::make_sandwich();
    }
    return b;
}

Naming conventions

Class and namespace names use UpperCamelCase. Global and public static functions, stack variables, and class members (class variables) use lower_snake_case. Class member functions (methods) use lowerCamelCase. Protected and private class members are prefixed with an underscore. Macros and constants use UPPER_SNAKE_CASE. Template parameters which are types use UpperCamelCase, while those which are integers use UPPER_SNAKE_CASE, like constants. Type prefixes, Hungarian notation, etc. are disallowed. Use meaningful suffixes if you need to disambiguate, e.g. text_raw and text_escaped.

Variable names should be nouns. Function names should be verbs, with the exception of getters, which can be nouns. For instance, a class property called position would have the setter setPosition() and the getter position().

Filename conventions

All files which are part of the Inkscape source should use lowercase-with-hyphens. C++ files should have the .cpp extension, while header files should have the .h extension. Spaces, uppercase letters and underscores are not allowed. Using numbers in filenames is discouraged.

#define SOME_MACRO(x) x
void call_global();
unsigned const IMPORTANT_CONSTANT = 42;

class Example {
public:
    void callPublic();
    static void call_public_static();
    int public_variable;
protected:
    void _callProtected();
    static _call_protected_static();
    int _protected_variable;
private:
    void _callPrivate();
    static void _call_private_static();
    int _private_variable;
};

template <typename TypeParam, int INTEGER_PARAM>
void call_global_template(boost::array<TypeParam, INTEGER_PARAM> const &array);

Placement of const

The const qualifier binds to the right, not to the left. This fact is often forgotten, so in order for everyone to keep this in mind, we require the const qualifier to be written after the type.

void paste_sticker(std::string const &label);
char const *mutable_pointer_to_const_string;
char *const const_pointer_to_mutable_string;
char const *const const_pointer_to_const_string;
int const integral_constant = 42;

Preprocessor

Conditional compilation using the preprocessor is strongly discouraged, since it leads to code rot. Use it only when it is unavoidable, for instance when an optional dependency is used. A special case is using conditional compilation to exclude an entire file based on the platform, which is allowed.

In preference to conditionally compiled, platform-specific code, you should aim to write portable code which works the same regardless of platform. Using the GLib and GTK+ libraries can help a lot in this respect. If you must use different code depending on the platform, try to encapsulate it in helper functions, so that the amount of code that differs between platforms is kept to a minimum.

File layout

Inkscape files have a fixed layout. Each code file should contain things in this order:

  1. A Doxygen comment with a brief description of what's in the file.
  2. A separate non-Doxygen comment with author and licensing information.
  3. Open of include guard (only in headers).
  4. System header includes, e.g. #include <header>. These headers should either be ordered alphabetically or ordered by library dependencies.
  5. Internal header includes, e.g. #include "header.h". These headers should be ordered alphabetically.
  6. The code itself, in the Inkscape namespace. Here the order is more flexible, but usually global function declarations should come after class declarations. The order of definitions in the .cpp file should match the order of declarations in the .h file.
  7. Close of include guard.
  8. A comment with standard modelines for Vim and Emacs, also usable by other editors. This block is the same for all files.

The code below demonstrates a small example file which conforms to the required layout.

/** @file
 * Selector component (click and rubberband)
 *//*
 * Authors:
 *   Krzysztof Kosiński <tweenk.pl@gmail.com>
 *
 * Copyright (C) 2009 Authors
 * Released under GNU GPL, read the file 'COPYING' for more information
 */

#ifndef SEEN_UI_TOOL_SELECTOR_H
#define SEEN_UI_TOOL_SELECTOR_H

#include <memory>
#include <gdk/gdk.h>
#include <2geom/rect.h>
#include "ui/tool/manipulator.h"

class SPDesktop;
class CtrlRect;

namespace Inkscape {
namespace UI {

class SelectorPoint;

class Selector : public Manipulator {
public:
    Selector(SPDesktop *d);
    virtual ~Selector();
    virtual bool event(SPEventContext *, GdkEvent *);
    
    sigc::signal<void, Geom::Rect const &, GdkEventButton*> signal_area;
    sigc::signal<void, Geom::Point const &, GdkEventButton*> signal_point;
private:
    SelectorPoint *_dragger;
    Geom::Point _start;
    CtrlRect *_rubber;
    gulong _connection;
    bool _cancel;
    friend class SelectorPoint;
};

} // namespace UI
} // namespace Inkscape

#endif

/*
  Local Variables:
  mode:c++
  c-file-style:"stroustrup"
  c-file-offsets:((innamespace . 0)(inline-open . 0)(case-label . +))
  indent-tabs-mode:nil
  fill-column:99
  End:
*/
// vim: filetype=cpp:expandtab:shiftwidth=4:tabstop=8:softtabstop=4:fileencoding=utf-8:textwidth=99 :

Source code formatters

The task of keeping the source files conformant to the coding style can be simplified by using automatic source code formatters.

Artistic Style options

Artistic Style (astyle) is a C++ source code formatter. You can use it to reformat any nonconformant source code. For the Inkscape coding style, put the following in your .astylerc file:

--style=stroustrup
--indent=spaces=4
--indent-preprocessor
--indent-col1-comments
--pad-oper
--unpad-paren
--pad-header
--align-pointer=name
--align-reference=name
--add-brackets
--convert-tabs

The same content is available in the astylerc file in Inkscape's source code repository, which you can pass as the argument to the --options option. You can also use an equivalent command line.

astyle --options=astylerc
astyle -A4 -s4 -k3 -W3 -cjHpUwY

clang-format options

clang-format is a source code formatter shipped as part of the Clang compiler, based on LLVM. Recent revisions of Inkscape come with a suitable _clang-format file, which means clang-format should pick up the correct settings out of the box.