mirror-chatterino2/CONTRIBUTING.md

Chatterino code guidelines

This is a set of guidelines for contributing to Chatterino. The goal is to teach programmers without a C++ background (java/python/etc.), people who haven't used Qt, or otherwise have different experience, the idioms of the codebase. Thus we will focus on those which are different from those other environments. There are extra guidelines available here but they are considered as extras and not as important.

General (non-code related) guidelines for contributing to Chatterino

• Make a specific branch for your pull request instead of using the master, main, or mainline branch. This will prevent future problems with updating your branch after your PR is merged.

Tooling

Formatting

Code is automatically formatted using clang-format. It takes the burden off of the programmer and ensures that all contributors use the same style (even if mess something up accidentally). We recommend that you set up automatic formatting on file save in your editor.

Comments

Comments should only be used to:

• Increase readability (e.g. grouping member variables).
• Containing information that can't be expressed in code.

Try to structure your code so that comments are not required.

Good example

/// Result is 0 if a == b, negative if a < b and positive if b > a.
/// ^^^ You can't know this from the function signature!
//      Even better: Return a "strong ordering" type.
//          (but we don't have such a type right now)
int compare(const QString &a, const QString &b);

Bad example

/*
 * Matches a link and returns std::nullopt if it failed and a
 * QRegularExpressionMatch on success.
 * ^^^ This comment just repeats the function signature!!!
 *
 * @param text The text that will be checked if it contains a
 * link
 * ^^^ No need to repeat the obvious.
 */
std::optional<QRegularExpressionMatch> matchLink(const QString &text);

Code

Arithmetic Types

Arithmetic types (like char, short, int, long, float and double), bool, and pointers are NOT initialized by default in c++. They keep whatever value is already at their position in the memory. This makes debugging harder and is unpredictable, so we initialize them to zero by using {} after their name when declaring them.

class ArithmeticTypes
{
    int thisIs0{};
    QWidget *thisIsNull{};
    bool thisIsFalse_{};
    // int a; // <- Initialized to "random" value.
    // QWidget *randomPtr.

    std::vector<int> myVec; // <- other types call constructors instead, so no need for {}
    // std::vector<int> myVec{}; <- pointless {}

    int thisIs5 = 5; // <- Also fine, we initialize it with another value.
};

void myFunc() {
    int a = 1 + 1; // <- here we initialize it immediately, so it's fine.
}

Passing parameters

The way a parameter is passed, signals how it is going to be used inside of the function. C++ doesn't have multiple return values, so there are "out parameters" (reference to a variable that is going to be assigned inside of the function) to simulate multiple return values.

Cheap to copy types like int/enum/etc. can be passed in per value since copying them is fast.

void setValue(int value) {
    // ...
}

References mean that the variable doesn't need to be copied when it is passed to a function.

type	meaning
const Type& name	in Parameter. It is NOT going to be modified and may be copied inside of the function.
Type& name	out or in+out Parmameter. It will be modified.

Pointers signal that objects are managed manually. While the above are only guaranteed to live as long as the function call (= don't store and use later) these may have more complex lifetimes.

type	meaning
Type* name	The lifetime of the parameter may exceed the length of the function call. It may use the QObject parent/children system.

R-value references && work similar to regular references but signal the parameter should be "consumed".

void storeLargeObject(LargeObject &&object) {
    // ...
}

void storeObject(std::unique_ptr<Object> &&object) {
    // ...
}

void main() {
    // initialize a large object (= will be expensive to copy)
    LargeObject large = // ...

    // Object accepts an r-value reference + we use std::move()
    // => We move the object = no need to copy.
    storeLargeObject(std::move(large));

    // But even worse, you can't copy a unique_ptr so we need to move here!
    std::unique_ptr<Object> unique = // ...
    storeObject(std::move(unique));

    // The pointer contained by unique has now been consumed by "storeObject"
    // so it just holds a null pointer now.
    assert(unique.get() == nullptr);
}

Generally the lowest level of requirement should be used, e.g. passing Channel& instead of std::shared_ptr<Channel>& (aka ChannelPtr) if possible.

Members

All function names are in camelCase. Private member variables are in camelCase_ (note the underscore at the end). We don't use the get prefix for getters. We mark functions as const if applicable.

class NamedObject
{
public:
    const QString &name() const; // <- no "get" prefix.
    void setName(const QString &name);
    bool hasLongName() const; // <- "has" or "is" prefix is okay

    static void myStaticFunction(); // <- also lowercase
    QString publicName;

private:
    // Private variables have "_" suffix.
    QString name_;
    // QString name; <- collides with name() function
};

void myFreeStandingFunction(); // <- also lower case

Casts

• Avoid c-style casts: (type)variable.
• Instead use explicit type casts: type(variable)
• Or use one of static_cast, const_cast and dynamic_cast
• Try to avoid reinterpret_cast unless necessary.

void example() {
    float f = 123.456;
    int i = (int)f; // <- don't
    int i = int(f); // <- do

    Base* base = // ...
    Derived* derived = (Derived*)base;               // <- don't
    Derived* derived = dynamic_cast<Derived*>(base); // <- do

    // Only use "const_cast" solved if using proper const correctness doesn't work.
    const int c = 123;
    ((int &)c) = 123;           // <- don't
    const_cast<int &>(c) = 123; // <- do (but only sometimes)

    // "reinterpret_cast" is also only required in very rarely.
    int p = 123;
    float *pp = (float*)&p;
    float *pp = reinterpret_cast<float*>(&p);
}

This

Always use this to refer to instance members to make it clear where we use either locals or members.

class Test
{
    void testFunc(int a);
    int testInt_{};
}

Test::testFunc(int a)
{
    // do
    this->testInt_ += 2;
    this->testFunc();

    // don't
    testInt_ -= 123;
    testFunc(2);
    this->testFunc(testInt_ + 1);
}

Managing resources

Regular classes

Keep the element on the stack if possible. If you need a pointer or have complex ownership you should use one of these classes:

• Use std::unique_ptr if the resource has a single owner.
• Use std::shared_ptr if the resource has multiple owners.

QObject classes

• Use the object tree to manage lifetimes where possible. Objects are destroyed when their parent object is destroyed.
• If you have to explicitly delete an object use variable->deleteLater() instead of delete variable. This ensures that it will be deleted on the correct thread.
• If an object doesn't have a parent, consider using std::unique_ptr<Type, DeleteLater> with DeleteLater from "src/common/Common.hpp". This will call deleteLater() on the pointer once it goes out of scope, or the object is destroyed.

Conventions

Usage strings

When informing the user about how a command is supposed to be used, we aim to follow this standard where possible.

• Square brackets are reserved for [optional arguments].
• Angle brackets are reserved for <required arguments>.
• The word Usage should be capitalized and must be followed by a colon.
• If the usage deserves a description, put a dot after all parameters and explain it briefly.

Good

• Usage: /block <user>
• Usage: /unblock <user>. Unblocks a user.
• Usage: /streamlink [channel]
• Usage: /usercard <user> [channel]

Bad

• Usage /streamlink <channel> - Missing colon after Usage.
• usage: /streamlink <channel> - Usage must be capitalized.
• Usage: /streamlink channel - The required argument channel must be wrapped in angle brackets.
• Usage: /streamlink <channel>. - Don't put a dot after usage if it's not followed by a description.