skia2/site/dev/contrib/style.md

Coding Style Guidelines

These conventions have evolved over time. Some of the earlier code in both projects doesn't strictly adhere to the guidelines. However, as the code evolves we hope to make the existing code conform to the guildelines.

Files

We use .cpp and .h as extensions for c++ source and header files.

Headers that aren't meant for public consumption should be placed in src directories so that they aren't in a client's search path, or in include/private if they need to be used by public headers.

We prefer to minimize includes. If forward declaring a name in a header is sufficient then that is preferred to an include.

Forward declarations and file includes should be in alphabetical order (but we aren't very strict about it).

Do not use #if/#ifdef before including "SkTypes.h" (directly or indirectly). Most things you'd #if on tend to not yet be decided until SkTypes.h.

We use 4 spaces, not tabs.

We use Unix style endlines (LF).

We prefer no trailing whitespace but aren't very strict about it.

We wrap lines at 100 columns unless it is excessively ugly (use your judgement). The soft line length limit was changed from 80 to 100 columns in June 2012. Thus, most files still adhere to the 80 column limit. It is not necessary or worth significant effort to promote 80 column wrapped files to 100 columns. Please don't willy-nilly insert longer lines in 80 column wrapped files. Either be consistent with the surrounding code or, if you really feel the need, promote the surrounding code to 100 column wrapping.

Naming

Both projects use a prefix to designate that they are Skia prefix for classes, enums, structs, typedefs etc is Sk. Ganesh's is Gr. Nested types should not be prefixed.

class SkClass {
public:
    class HelperClass {
        ...
    };
};

Data fields in structs, classes, unions begin with lowercase f and are then camel capped.

struct GrCar {
    ...
    float fMilesDriven;
    ...
};

Globals variables are similar but prefixed with g and camel-capped

bool gLoggingEnabled
Local variables begin lowercases and are camel-capped.

int herdCats(const Array& cats) {
    int numCats = cats.count();
}

Enum values are prefixed with k. Unscoped enum values are post fixed with an underscore and singular name of the enum name. The enum itself should be singular for exclusive values or plural for a bitfield. If a count is needed it is k<singular enum name>Count and not be a member of the enum (see example), or a kLast member of the enum is fine too.

enum class SkPancakeType {
     kBlueberry,
     kPlain,
     kChocolateChip,
};

enum SkPancakeType {
     kBlueberry_PancakeType,
     kPlain_PancakeType,
     kChocolateChip_PancakeType,

     kLast_PancakeType = kChocolateChip_PancakeType
};

static const SkPancakeType kPancakeTypeCount = kLast_PancakeType + 1;

A bitfield:

enum SkSausageIngredientBits {
    kFennel_SuasageIngredientBit = 0x1,
    kBeef_SausageIngredientBit   = 0x2
};

or:

enum SkMatrixFlags {
    kTranslate_MatrixFlag = 0x1,
    kRotate_MatrixFlag    = 0x2
};

Exception: anonymous enums can be used to declare integral constants, e.g.:

enum { kFavoriteNumber = 7 };

Macros are all caps with underscores between words. Macros that have greater than file scope should be prefixed SK or GR.

Static non-class functions in implementation files are lower case with underscores separating words:

static inline bool tastes_like_chicken(Food food) {
    return kIceCream_Food != food;
}

Externed functions or static class functions are camel-capped with an initial cap:

bool SkIsOdd(int n);

class SkFoo {
public:
    static int FooInstanceCount();
};

Macros

Ganesh macros that are GL-specific should be prefixed GR_GL.

#define GR_GL_TEXTURE0 0xdeadbeef

Ganesh prefers that macros are always defined and the use of #if MACRO rather than #ifdef MACRO.

#define GR_GO_SLOWER 0
...
#if GR_GO_SLOWER
    Sleep(1000);
#endif

Skia tends to use #ifdef SK_MACRO for boolean flags.

Braces

Open braces don't get a newline. else and else if appear on same line as opening and closing braces unless preprocessor conditional compilation interferes. Braces are always used with if, else, while, for, and do.

if (...) {
    oneOrManyLines;
}

if (...) {
    oneOrManyLines;
} else if (...) {
    oneOrManyLines;
} else {
    oneOrManyLines;
}

for (...) {
    oneOrManyLines;
}

while (...) {
    oneOrManyLines;
}

void function(...) {
    oneOrManyLines;
}

if (!error) {
    proceed_as_usual();
}
#if HANDLE_ERROR
else {
    freak_out();
}
#endif

Flow Control

There is a space between flow control words and parentheses and between parentheses and braces:

while (...) {
}

do {
} while(...);

switch (...) {
...
}

Cases and default in switch statements are indented from the switch.

switch (color) {
    case kBlue:
        ...
        break;
    case kGreen:
        ...
        break;
    ...
    default:
       ...
       break;
}

Fallthrough from one case to the next is commented unless it is trivial:

switch (recipe) {
    ...
    case kCheeseOmelette_Recipe:
        ingredients |= kCheese_Ingredient;
        // fallthrough
    case kPlainOmelette_Recipe:
        ingredients |= (kEgg_Ingredient | kMilk_Ingredient);
        break;
    ...
}

When a block is needed to declare variables within a case follow this pattern:

switch (filter) {
    ...
    case kGaussian_Filter: {
        Bitmap srcCopy = src->makeCopy();
        ...
        break;
    }
    ...
};

Classes

Unless there is a need for forward declaring something, class declarations should be ordered public, protected, private. Each should be preceded by a newline. Within each visibility section (public, private), fields should not be intermixed with methods. It's nice to keep all data fields together at the end.

class SkFoo {

public:
    ...

protected:
    ...

private:
    void barHelper(...);
    ...

    SkBar fBar;
    ...
};

Subclasses should have a private typedef of their super class called INHERITED:

class GrDillPickle : public GrPickle {
    ...
private:
    typedef GrPickle INHERITED;
};

Virtual functions that are overridden in derived classes should use override, and the virtual keyword should be omitted.

void myVirtual() override {
}

All references to base-class implementations of a virtual function should be explicitly qualified:

void myVirtual() override {
    ...
    this->INHERITED::myVirtual();
    ...
}

Constructor initializers should be one per line, indented, with punctuation placed before the initializer. This is a fairly new rule so much of the existing code is non-conforming. Please fix as you go!

GrDillPickle::GrDillPickle()
    : GrPickle()
    , fSize(kDefaultPickleSize) {
    ...
}

Constructors that take one argument should almost always be explicit, with exceptions made only for the (rare) automatic compatibility class.

class Foo {
    explicit Foo(int x);  // Good.
    Foo(float y);         // Spooky implicit conversion from float to Foo.  No no no!
    ...
};

Method calls within method calls should be prefixed with dereference of the 'this' pointer. For example:

this->method();

Integer Types

We follow the Google C++ guide for ints and are slowly making older code conform to this

(http://google-styleguide.googlecode.com/svn/trunk/cppguide.xml#Integer_Types)

Summary: Use int unless you have need a guarantee on the bit count, then use stdint.h types (int32_t, etc). Assert that counts, etc are not negative instead of using unsigned. Bitfields use uint32_t unless they have to be made shorter for packing or performance reasons.

nullptr, 0

Use nullptr for pointers, 0 for ints. We suggest explicit nullptr comparisons when checking for nullptr pointers, as documentation:

if (nullptr == x) {  // slightly preferred over if (!x)
   ...
}

When checking non-nullptr pointers we think implicit comparisons read better than an explicit comparison's double negative:

if (x) {  // slightly preferred over if (nullptr != x)
   ...
}

Function Parameters

Mandatory constant object parameters are passed to functions as const references. Optional constant object parameters are passed to functions as const pointers. Mutable object parameters are passed to functions as pointers. We very rarely pass anything by non-const reference.

// src and paint are optional
void SkCanvas::drawBitmapRect(const SkBitmap& bitmap, const SkIRect* src,
                              const SkRect& dst, const SkPaint* paint = nullptr);

// metrics is mutable (it is changed by the method)
SkScalar SkPaint::getFontMetrics(FontMetric* metrics, SkScalar scale) const;

If function arguments or parameters do not all fit on one line, the overflowing parameters may be lined up with the first parameter on the next line

void drawBitmapRect(const SkBitmap& bitmap, const SkRect& dst,
                    const SkPaint* paint = nullptr) {
    this->drawBitmapRectToRect(bitmap, nullptr, dst, paint,
                               kNone_DrawBitmapRectFlag);
}

or all parameters placed on the next line and indented eight spaces

void drawBitmapRect(
        const SkBitmap& bitmap, const SkRect& dst,
        const SkPaint* paint = nullptr) {
    this->drawBitmapRectToRect(
            bitmap, nullptr, dst, paint, kNone_DrawBitmapRectFlag);
}

Python

Python code follows the Google Python Style Guide.