> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/serenityOS/serenity/llms.txt
> Use this file to discover all available pages before exploring further.

# Coding Style

> C++ coding style guide for SerenityOS

For low-level styling (spaces, parentheses, brace placement, etc), all code should follow the format specified in `.clang-format` in the project root.

<Warning>
  **Important:** Make sure you use `clang-format` version 20 or later!
</Warning>

This document describes the coding style used for C++ code in the Serenity Operating System project. All new code should conform to this style.

## Names

A combination of CamelCase, snake\_case, and SCREAMING\_CASE:

* Use **CamelCase** (Capitalize the first letter, including all letters in an acronym) in a class, struct, or namespace name
* Use **snake\_case** (all lowercase, with underscores separating words) for variable and function names
* Use **SCREAMING\_CASE** for constants (both global and static member variables)

### Right:

```cpp theme={null}
struct Entry;
size_t buffer_size;
class FileDescriptor;
String absolute_path();
```

### Wrong:

```cpp theme={null}
struct data;
size_t bufferSize;
class Filedescriptor;
String MIME_Type();
```

<Tip>
  Use full words, except in the rare case where an abbreviation would be more canonical and easier to understand.
</Tip>

### Data Members

Data members in C++ classes should be private. Static data members should be prefixed by `s_`. Other data members should be prefixed by `m_`. Global variables should be prefixed by `g_`.

```cpp theme={null}
class String {
public:
    ...

private:
    int m_length { 0 };
};
```

### Getters and Setters

Precede setters with the word "set". Use bare words for getters. Setter and getter names should match the names of the variables being set/gotten.

```cpp theme={null}
void set_count(int); // Sets m_count.
int count() const; // Returns m_count.
```

Precede getters that return values through out arguments with the word "get".

```cpp theme={null}
void get_filename_and_inode_id(String&, InodeIdentifier&) const;
```

### Function Names

Use descriptive verbs in function names.

```cpp theme={null}
bool convert_to_ascii(short*, size_t);
```

<Note>
  When there are two getters for a variable, and one of them automatically makes sure the requested object is instantiated, prefix that getter function with `ensure_`. As it ensures that an object is created, it should consequently also return a reference, not a pointer.

  ```cpp theme={null}
  Inode* inode();
  Inode& ensure_inode();
  ```
</Note>

### Function Parameters

Leave meaningless variable names out of function declarations. A good rule of thumb is if the parameter type name contains the parameter name (without trailing numbers or pluralization), then the parameter name isn't needed.

```cpp theme={null}
void set_count(int);
void do_something(Context*);
```

Prefer enums to bools on function parameters if callers are likely to be passing constants, since named constants are easier to read at the call site.

```cpp theme={null}
do_something(something, AllowFooBar::Yes);
paint_text_with_shadows(context, ..., text_stroke_width > 0, is_horizontal());
set_resizable(false);
```

### Enums and Constants

Enum members should use InterCaps with an initial capital letter.

Prefer `const` to `#define`. Prefer inline functions to macros.

`#defined` constants should use all uppercase names with words separated by underscores.

### Header Guards

Use `#pragma once` instead of `#define` and `#ifdef` for header guards.

```cpp theme={null}
// MyClass.h
#pragma once
```

## Other Punctuation

### Constructors

Constructors for C++ classes should initialize their members using C++ initializer syntax. Each member (and superclass) should be indented on a separate line, with the colon or comma preceding the member on that line. Prefer initialization at member definition whenever possible.

```cpp theme={null}
class MyClass {
    ...
    Document* m_document { nullptr };
    int m_my_member { 0 };
};

MyClass::MyClass(Document* document)
    : MySuperClass()
    , m_document(document)
{
}
```

### Iterators

Prefer index or range-for over iterators in Vector iterations for terse, easier-to-read code.

```cpp theme={null}
// Preferred
for (auto& child : children)
    child->do_child_thing();

// OK
for (int i = 0; i < children.size(); ++i)
    children[i]->do_child_thing();

// Wrong
for (auto it = children.begin(); it != children.end(); ++it)
    (*it)->do_child_thing();
```

## Pointers and References

Both pointer types and reference types should be written with no space between the type name and the `*` or `&`.

An out argument of a function should be passed by reference except rare cases where it is optional in which case it should be passed by pointer.

```cpp theme={null}
void MyClass::get_some_value(OutArgumentType& out_argument) const
{
    out_argument = m_value;
}

void MyClass::do_something(OutArgumentType* out_argument) const
{
    do_the_thing();
    if (out_argument)
        *out_argument = m_value;
}
```

## "using" Statements

In header files in the AK sub-library, it is acceptable to use "using" declarations at the end of the file to import one or more names in the AK namespace into the global scope.

```cpp theme={null}
// AK/Vector.h

namespace AK {

} // namespace AK

using AK::Vector;
```

<Warning>
  In C++ implementation files, do not use "using" declarations of any kind to import names in the standard template library. Directly qualify the names at the point they're used instead.
</Warning>

## Types

Omit "int" when using "unsigned" modifier. Do not use "signed" modifier. Use "int" by itself instead.

```cpp theme={null}
// Right
unsigned a;
int b;

// Wrong
unsigned int a; // Doesn't omit "int".
signed b; // Uses "signed" instead of "int".
```

## Classes

For types with methods, prefer `class` over `struct`.

* For classes, make public getters and setters, keep members private with `m_` prefix.
* For structs, let everything be public and skip the `m_` prefix.

```cpp theme={null}
struct Thingy {
    String name;
    int frob_count { 0 };
};

class Doohickey {
public:
    String const& name() const { return m_name; }
    int frob_count() const { return m_frob_count; }

    void jam();

private:
    String m_name;
    int m_frob_count { 0 };
}
```

### Constructors and Type Conversion

Use a constructor to do an implicit conversion when the argument is reasonably thought of as a type conversion and the type conversion is fast. Otherwise, use the explicit keyword or a function returning the type.

```cpp theme={null}
class LargeInt {
public:
    LargeInt(int);
...

class Vector {
public:
    explicit Vector(int size); // Not a type conversion.
    Vector create(Array); // Costly conversion.
...
```

### Singleton Pattern

Use a static member function named "the()" to access the instance of the singleton.

```cpp theme={null}
class UniqueObject {
public:
    static UniqueObject& the();
...
```

## Comments

Make comments look like sentences by starting with a capital letter and ending with a period (punctuation). One exception may be end of line comments like this `if (x == y) // false for NaN`.

Use FIXME: (without attribution) to denote items that need to be addressed in the future.

```cpp theme={null}
draw_jpg(); // FIXME: Make this code handle jpg in addition to the png support.
```

<Tip>
  Explain *why* the code does something. The code itself should already say what is happening.

  ```cpp theme={null}
  // Good
  i++; // Go to the next page.

  // Better
  page_index++;

  // Wrong
  i++; // Increment i.
  ```
</Tip>

## Overriding Virtual Methods

The declaration of a virtual method inside a class must be declared with the `virtual` keyword. All subclasses of that class must also specify either the `override` keyword when overriding the virtual method, or the `final` keyword when overriding the virtual method and requiring that no further subclasses can override it.

```cpp theme={null}
class Person {
public:
    virtual String description() { ... };
}

class Student : public Person {
public:
    virtual String description() override { ... };
}
```

## Const Placement

Use "east const" style where `const` is written on the right side of the type being qualified.

```cpp theme={null}
// Right
Salt const& m_salt;

// Wrong
const Salt& m_salt;
```

## Casts

Before you consider a cast, please see if your problem can be solved another way that avoids the visual clutter.

<Warning>
  **Don't use C-style casts.** The C-style cast has complex behavior that is undesired in many instances. Be aware of what sort of type conversion the code is trying to achieve, and use the appropriate C++ cast operator, like `static_cast`, `reinterpret_cast`, `bit_cast`, `dynamic_cast` etc.

  There is a single exception to this rule: marking a function parameter as used with `(void)parameter;`.
</Warning>

```cpp theme={null}
// Right
MyParentClass& object = get_object();
MyChildClass& casted = static_cast<MyChildClass&>(object);
```

## Omission of Curly Braces

Curly braces may only be omitted from `if`/`else`/`for`/`while`/etc. statement blocks if the body is a single line.

Additionally, if any body of a connected if/else statement requires curly braces according to this rule, all of them do.

```cpp theme={null}
// Right
if (condition)
    foo();

if (condition) {
    foo();
    bar();
}

if (condition) {
    foo();
} else if (condition) {
    bar();
    baz();
} else {
    qux();
}
```