Project: Redpanda (App Definition and Development / Streaming & Messaging)
File: coding-style.md

The document covers style and convention not enforced by clang-format. Header files have the `.h` extension, source files use the `.cc` extension. Public header files (meaning other libraries can `#include` them directly), should go in an `includes` directory within the library they belong to. For example, a library named `foo` should have public header files within `src/v/foo/include/foo`. Test files go in the `tests` directory of the library they belong to. That is, the tests for a feature named `foo` and located in `src/v/foo` will be located in `src/v/foo/tests`. Use `snake_case` naming convention by default for files and language identifiers. The audience when writing comments should be for other members of your team, new members of the team getting onboarded, and an oncaller who is trying to re-familiarize themselves with some code. Here are some generic tips for writing good technical comments: If writing something in-depth, start with a summary to prevent overloading someone new. Write as close to the source as possible, and try not to duplicate comments, but reference the source. If in doubt, write something concise and to the point. Don't add fluff for the sake of it. Think about the maintainablility of your comments. For the curious, here are some useful articles on this subject: Modules themselves should have a `README.md` file explaining the purpose of the library, its API surface, and an architectural overview of that library (mentioning major classes), etc. This will aid people new to the library in understanding the lay of the land. When in doubt of if information should be placed in a class or in a README, prefer moving the documentation as close to the source as possible (inside the class documentation). We want to prioritize documentation not becoming stale - and also not cognitively overload the reader of the library README. All classes and structs should be documented. Writing points when documenting a given class: Lifecycle of the class Place within the larger library How to use it correctly (concurrency, proper setup, example usage, etc). Broad strokes of implmentation details Which cores it exists on (if a sharded service) If it is a cluster/node/shard view of information For a struct, it is useful to document how/where it is used, as well as the meaning of it's members. Non trivial free and class functions should be documented. Trivial is ultimately a judgement call, but a rule of thumb is that getter methods (like `iobuf value() const { return _value; }`) or other common lifecycle methods like `start` and `stop` could be considered trivial. It's highly recommended to error on the side of having something rather than nothing when documenting functions however. In any file, to include a header file (one in the `src/v` directory), use an absolute path with `""` like this: ```c++ ``` Header files included from dependencies should use system path convention: ```c++ ``` Use `#pragma once` instead of an include guard. ```c++ class type { public: protected: private: }; ``` It's okay to use multiple instances of access specifiers to create logical groupings where needed. ```c++ class type { public: // boiler plate public: // logical grouping of APIs ... }; ```