mirror-chatterino2/CONTRIBUTING.md

Chatterino code guidelines

This is a set of guidelines for contributing to Chatterino. The goal is to teach programmers without 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 this which are different from those other environments. There are extra guidelines available here but they are considered as extras and not as important.

Tooling

Formatting

Code is automatically formatted using clang-format. It take the burdon off of the programmer and ensures that all contributers 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 readablility (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 boost::none 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.
 */
boost::optional<QRegularExpressionMatch> matchLink(const QString &text);

Code

Arithmetic Types

Arithmetic types (like char, short, int, long, float and double), bool, and pointers are NOT inititalized 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 is "out parameters" (reference to a variable that is going to 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 functions 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 lifetime where possible. Objects are destroyed when their parent object is destroyed.
• If you have to explicitely 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.