# C Style Guide
This guide prioritizes horizontal code layout and readability with
a hard 80 character line limit.

---

## Naming Conventions
**Variables and Local Functions:**
- Use `snake_case`
- Example: `int user_count;`, `void process_data()`

**Constants:**
- Use `UPPER_SNAKE_CASE`
- Example: `Const int MAX_BUFFER_SIZE;`

**Type Aliases:**
- Use `PascalCase`
- Example: `typedef int *IntPtr;`

**Structs, Enums, and Unions:**
- Use `PascalCase`
- Example: `struct UserData { ... }`

**Pointers:**
- Place `*` adjacent to the variable name, not the type
- Example: `int *ptr;` not `int* ptr;`
- Example: `int *a, *b;` for multiple pointers

---

## Function Declarations
**Single-line functions with few arguments:**
```C
int add(int a, int b) {
    return a + b;
}
```

**Multi-argument functions:**
Place each argument on its own line for clarity.
```C
int calculate(
    int value1,
    int value2,
    int value3,
    int multiplier
) {
    return (value1 + value2 + value3) * multiplier;
}
```

**Long function names:**
Place the return type on its own line.
```C
int
very_long_function_name_for_complex_operation(int arg1, int arg2) {
    ...
}
```

**Long return types with multi-line arguments:**
```C
struct ComplexReturnType*
long_function_with_many_parameters(
    int param1,
    int param2,
    const char *string
) {
    ...
}
```

---

## Struct and Enum Definitions
**Basic structs:**
```C
struct Person {
    char *name;
    int age;
    float height;
};
```

**Enums:**
```C
enum Color {
    COLOR_RED,
    COLOR_GREEN,
    COLOR_BLUE
};
```

---

## Comments
- Use `//` for single-line comments
- Use `/* */` for multi-line comments
- Comments should explain *why*, not *what*

```C
// Initialize the connection pool with default size
int pool_size = INITIAL_POOL_SIZE;

/* This algorithm uses a two-pointer approach to optimize
   space complexity from O(n) to O(1) */
```

--

## Doxygen Documentation
Document public functions and structures using Doxygen-style comments
with `/**`. Include descriptions of parameters, return values, and
potential error conditions. This enables automatic API documentation
generation and improves IDE support. Use `@param`, `@return`, and
`@brief` tags. Keep documentation concise and focused on the interface,
not implementation details. Private functions may use standard comments.

```C
/**
 * @brief Calculate sum of two integers
 * @param a First operand
 * @param b Second operand
 * @return Sum of a and b
 */
int add(int a, int b) {
    return a + b;
}

/**
 * @brief Allocate and initialize user data
 * @param name User's name (must not be NULL)
 * @param age User's age (must be positive)
 * @return Pointer to allocated UserData or NULL on failure
 */
struct UserData*
create_user(const char *name, int age);
```

---

## Indentation
- Use 4 spaces per indentation level
- No tabs

```C
void example() {
    if (condition) {
        do_something();
    }
}
```

## Braces
- Opening brace on same line (K&R style)
- Closing brace on its own line

```C
if (x > 0) {
    process();
} else {
    handle_error();
}
```

## Memory Management
- `malloc` calls should be cast and checked
- Free resources in reverse allocation order
- Use meaningful variable names for allocated memory

```C
int *buffer = (int *)malloc(size * sizeof(int));
if (!buffer) {
    return ERROR_OUT_OF_MEMORY;
}
```

---

## Macro Definitions
- Use `UPPER_SNAKE_CASE`
- Wrap macro bodies in parentheses
- Avoid side effects

```C
#define MAX(a, b) (((a) > (b)) ? (a) : (b))
#define BUFFER_SIZE 1024
```

## Spacing
- One space after keywords: `if`, `while`, `for`, etc.
- One space around binary operators: `+`, `-`, `==`, etc.
- No space before function argument parentheses

```C
int result = a + b;
if (result > 0) {
    for (int i = 0; i < 10; i++) {
        function_call(i);
    }
}
```

## File Names
- Use `snake_case`
- Use `.c` extension for source files.
- Use `.h` extension for header files.
- Example: `user_manager.c`, `user_manager.h`.

## Naming Conventions
- Choose descriptive names that eeflect
  the module's primary responsibility.
- Keep names concise but meaningful (typically 1-3 words).
- Avoid abbreviations unless they are widely recognized.
- Example: `config_parser.c` [good], `cfg_prs.c` [bad].

## Header File Guards
- Use `ifndef` guards with `UPPER_SNAKE_CASE`.
- Follow the pattern: `{FILENAME}_H` or `{FILENAME}_H_INCLUDED`.
- Example: `#ifndef USER_MANAGER_H`