Add 'Clean Code' and 'C++ Code Style' sections to the 'Conventions' document

AGENTS.md

@@ -0,0 +1,13 @@
+# Agent Instructions
+
+## Conventions
+
+Follow [docs/conventions.md](docs/conventions.md).
+
+## Build & Test
+
+See [docs/development.md](docs/development.md) for build, test, and formatting instructions.
+
+## Architecture
+
+See [docs/design.md](docs/design.md) for the library's architecture and design rationale.

CONTRIBUTING.md

@@ -2,10 +2,12 @@
 
 Pull requests for bug fixes are welcome.
 
-Before submitting new features or changes to current functionality, [open an
+Before submitting new features or changes to current functionality, please [open an
 issue](https://github.com/DataDog/dd-trace-cpp/issues/new) and discuss your ideas or propose the
 changes you wish to make. After a resolution is reached, a PR can be submitted for review.
 
-Please refer to the [documentation](docs) to learn about the architecture of the Datadog of C++ Tracing
-Library and the development processes, notably testing and code formatting, which are mandatory before
-submitting code changes.
+Sefer to the [documentation](docs) to learn about the architecture of the Datadog C++ Tracer Library
+and its development processes. In particular, review:
+
+- [Conventions](docs/conventions.md);
+- [Development Processes](docs/development.md).

docs/README.md

@@ -3,5 +3,5 @@
 This directory contains documentation of the Datadog C++ Tracer, including:
 
 - [Design](design.md)
-- [Conventions and Rationale](conventions.md)
+- [Conventions](conventions.md)
 - [Development Processes](development.md)

docs/conventions.md

@@ -1,21 +1,28 @@
-# Datadog C++ Tracer Conventions and Rationale
+# Datadog C++ Tracer Conventions
+
+This document defines repository-wide conventions for `dd-trace-cpp`. Apply these conventions to all
+new and modified code.
 
 ## C++ Version
 
-We use **C++17** to ensure maximum compatibility.
+The project targets **C++17** for broad compatibility.
+
+All code must compile as C++17. Do not use features introduced in C++20 or later.
 
 ## Build Systems
 
-**CMake** is the primary build system supported, as documented in [the main Readme](../README.md). It is
-how downstreams consumers, such as the Datadog Nginx module, embed the library (see
+- **CMake** is the primary build system supported, as documented in [the main Readme](../README.md).
+Downstream consumers, such as the Datadog Nginx module, use CMake to embed the library (see
 [nginx-datadog/CMakeLists.txt](https://github.com/DataDog/nginx-datadog/blob/c29a57f/CMakeLists.txt#L121)).
-
-**Bazel** is used internally for CI and by the Envoy integration (see
+- **Bazel** is used internally for CI and by the Envoy integration (see
 [envoy/source/extensions/tracers/datadog/BUILD](https://github.com/envoyproxy/envoy/blob/9d47ea91cc/source/extensions/tracers/datadog/BUILD#L52)).
 
-## C Standard Libaries
+## C Standard Libraries
+
+The project supports:
 
-We support **glibc** (GUN C Library) and [**musl**](https://en.wikipedia.org/wiki/Musl) (notably used by Alpine Linux).
+- **glibc** (GNU C Library);
+- [**musl**](https://en.wikipedia.org/wiki/Musl) (notably used by Alpine Linux).
 
 ## C++ Standard Library vs Abseil
 
@@ -29,22 +36,42 @@ and
 
 ## Header Files Organization
 
-We separate public and private APIs. Public headers live in `include/datadog` and are the only ones exported. Internal headers live in `src` and are not installed.
+Public and private APIs are kept separate:
+
+- Public headers live in `include/datadog` and are the only ones exported.
+- Internal headers live in `src` and are not installed.
 
 ## Testing Frameworks
 
-**Catch2** is used for unit tests.
+- Use **Catch2** for unit tests.
+- Use **Google Benchmark** for performance benchmarks.
+
+## Clean Code
+
+- Use meaningful variable and function names.
+- Do not use single-letter variable names.
+- Avoid abbreviations, unless very common and unambiguous.
+- Avoid obvious comments.
+- Prefer clearer variable and function names over explanatory comments.
+- Keep functions small and focused (<~ 20 lines when practical).
+- When practical, place caller functions before callees, so the code can be read from top to bottom.
+
+## C++ Code Style
 
-**Google Benchmark** is used for performance benchmarks.
+- Use modern C++ idioms.
+- Prefer explicit types. Use `auto` only for very long type names (>~ 50 characters).
+- Never use C-style casts.
+- Use raw pointers only when absolutely necessary.
+- Use C++17 nested namespace syntax.
+- Minimize the number of `#include` lines. Do not enforce the include-what-you-use rule.
 
 ## Naming Conventions
 
-- `class TypeName;`
-- `.member_function();`
-- `free_function();`
-- `f(int func_arg);`
-- `int local_var;`
-- `int private_member_;`
-- `int public_member;`
-- `enum Color { red, green, blue };`
-- `which_one<TraceId, TraceID>`
+- class: `class TypeName;`
+- class member function: `.member_function();`
+- class public member: `int public_member;`
+- class private member: `int private_member_;`
+- free function: `free_function();`
+- function argument: `function(int func_arg);`
+- local variable: `int local_var;`
+- enumeration: `enum class Color { RED, GREEN, BLUE };`