Minecraft-Community-Edition/CODE_STYLE.md

C++ Code Style Guide

This document defines the official coding conventions for this project.
The goal is consistency, readability, maintainability, and performance.

---

1. Core Principles

• Prefer clarity to cleverness.
• Prefer data-oriented design where appropriate.
• Avoid unnecessary abstraction layers.
• Reduce boilerplate, especially trivial getters/setters.
• Write modern C++ (C++20 or newer).
• Keep systems modular and engine-agnostic.
• Consistency is more important than personal preference.

---

2. Naming Conventions

2.1 Types (Classes, Structs, Enums)

• Use PascalCase.
• Do not use prefixes like C_, E, or I.

class InputManager;
struct ImageData;
enum class KeyboardMode;

---

2.2 Functions

• Use camelCase.
• Start with a verb.
• Be descriptive.

void initialize();
bool isConnected();
void setDeadzone(float value);
ImageData& getImageData();

---

2.3 Variables

• Use camelCase.
• Be descriptive and meaningful.

int playerHealth;
float movementSpeed;
bool isActive;

---

2.4 Constants

• Use constexpr.
• Use UPPER_CASE.

constexpr int MAX_PLAYERS = 4;
constexpr float DEFAULT_DEADZONE = 0.15f;

---

2.5 Member Variables

• Use camelCase

class Image {
private:
    Vector2 size;
    std::string fileName;
};

---

3. Formatting

3.1 Indentation

• 1 tab per level.
• Do not use spaces.

3.2 Braces

• K&R style: opening braces on the same line.

if (condition) {
    doSomething();
}

class Player {
public:
    void update();
};

3.3 Line Length

• Maximum 100–120 characters.

---

4. Avoid Excessive Getters and Setters

Do not create trivial getters/setters for simple member access.

Avoid

std::string getFileName();
int getImageSizeX();
int getImageSizeY();

Prefer Structured Data Access

Image& imgInfo = img.getImageInfo();
imgInfo.size.x;
imgInfo.size.y;

• Encapsulation should protect invariants, not hide trivial data.
• Prefer returning references to structured data when possible.

---

5. Modern C++ Rules

5.1 Enum Classes

enum class KeyboardMode {
    Default,
    Numeric,
    Password
};

5.2 constexpr over #define

❌ Avoid:

#define MAX_TEXTURES 128

✅ Prefer:

constexpr int MAX_TEXTURES = 128;

5.3 nullptr

MyClass* ptr = nullptr;

5.4 Smart Pointers

std::unique_ptr<Texture> texture;
std::shared_ptr<Model> model;

• Avoid raw new and delete if it is possible.

---

6. Header Rules

• Use #pragma once.
• Keep headers minimal.
• Forward declare when possible.
• One primary class per file.
• Avoid unnecessary includes.

#pragma once

class Renderer;

---

7. Fully Qualified Method Definitions and Calls

To improve clarity in inheritance chains:

7.1 Method Definitions

All method definitions must use the class scope.

class Window {
public:
    void setPosition();
};

void Window::setPosition() {
    // implementation
}

---

7.2 Inherited Classes

Always define overridden methods with the derived class name.

class Console : public Window {
public:
    void setPosition() override;
};

void Console::setPosition() {
    // implementation
}

---

7.3 Fully Qualified Calls Across Inheritance

When calling base-class methods from a derived class, use the full inheritance chain.

class Window {
public:
    void setPosition();
};

class Console : public Window {
};

class Application : public Console {
public:
    Application();
};

Application::Application() {
    Application::Console::Window::setPosition();
}

• Makes it clear which method is being invoked.
• Recommended for deep inheritance hierarchies.

---

8. Inheritance Rules

• Use inheritance only for true "is-a" relationships.
• Prefer composition to inheritance.
• Always mark overridden functions with override.
• Avoid deep or ambiguous inheritance hierarchies.

---

---

9. Comments

• Explain why, not what.

❌ Bad:

// increment i
i++;

✅ Good:

// Skip metadata header element
i++;

---

10. Platform Independence

• Avoid Windows types (DWORD, HRESULT, etc.) in core modules.
• Avoid OS-specific APIs in core logic.
• Use fixed-width integer types.

uint32_t
int64_t
std::u16string

• Platform-specific code should be isolated.

---

11. Performance Guidelines

• Pass large objects by const&.
• Move objects when transferring ownership.
• Reserve container capacity when known.
• Avoid unnecessary heap allocations.
• Prefer stack allocation when possible.
• Avoid hidden copies.

---

12. File Organization

• One main class per file:

Image.hpp
Image.cpp

---

13. Documentation

• Public APIs must use Doxygen-style comments.

/// Sets the controller deadzone.
/// @param value Deadzone between 0.0 and 1.0
void setDeadzone(float value);

---

15. Summary

• Consistency is more important than personal preference.
• Trivial getters/setters should be avoided; structured data access is preferred.
• Fully qualified method calls in inheritance chains improve clarity.
• All new code must follow this style guide.