StyleGuide.txt

# Universal Code Style Guide

> Languages: TypeScript, TSX, C++, Go, Rust

---

## 1. Formatting

### 1.1 - Use Tabs for Indentation
All code **must use tab characters** for indentation. Spaces are forbidden.

### 1.2 - Limit Line Length to 120 Characters
Lines should not exceed 120 characters. Break long lines at logical boundaries (e.g., after operators, commas).

### 1.3 - Use K&R Bracing Style
Braces must open on the same line as control structures.

```cpp
if (x) {
	DoSomething();
}
```

### 1.4 - Trim Trailing Whitespace
No line should end in whitespace. All files must end with a newline.

---

## 2. Naming

### 2.1 - Use PascalCase for All Identifiers
Identifiers for variables, functions, types, classes, interfaces, and constants must use PascalCase.

```typescript
const MaxCount = 10;
class UserProfile { ... }
function LoadUserData() { ... }
```

### 2.2 - Use camelCase for Short Local Variables Only
Temporary or loop-local variables may use camelCase inside functions.

```typescript
for (let i = 0; i < MaxCount; i++) { ... }
```

### 2.3 - Do Not Use snake_case or ALL_CAPS
These naming styles are completely forbidden, including for constants, macros, or defines.

---

## 3. Error Handling

### 3.1 - Do Not Use Exceptions
Exception-based control flow is disallowed in all languages. This includes throw, try/catch, panic!, etc.

### 3.2 - Return Errors as Values
All functions must return errors as part of the return type (e.g., Result, std::expected, T, error).

### 3.3 - Handle All Errors Explicitly
Never suppress or discard errors. No .unwrap(), .expect(), or _ = err patterns unless explicitly tested.

---

## 4. Comments and Documentation

### 4.1 - The "No Redundancy" Rule
Comments must **NEVER** restate what the code is doing. If the code is readable, do not comment it.

❌ **STRICTLY FORBIDDEN:**
- Restating function, variable, or type names (e.g., `// jobStore stores jobs`).
- Describing control flow (e.g., `// Loop through items`).
- Describing syntax (e.g., `// Start server`).

### 4.2 - The "No Speculation" Rule
Comments must address the **current reality** of the code. Future-gazing or apologizing is unprofessional.

❌ **STRICTLY FORBIDDEN:**
- "For now..."
- "Maybe later..."
- "Temporary..."
- "Ideally..."

### 4.3 - Valid Comments (The "Why" Rule)
Comments are **ONLY** permitted if they explain **WHY** a specific, non-obvious engineering decision was made.

✅ **PERMITTED:**
- Explaining synchronization choices (e.g., "Mutex required here to prevent race condition X").
- Explaining algorithmic trade-offs (e.g., "Using O(n) scan because list is guaranteed small").
- Explaining external constraints (e.g., "API requires this specific format").

### 4.4 - Module Headers
Every file must start with a high-level header describing the **purpose** and **responsibility** of the module.

```go
/**
 * API Server Module.
 *
 * Handles HTTP requests for file downloads and job status polling.
 * Implements an asynchronous worker pattern to non-blocking UI interactions.
 *
 * Author: KleaSCM
 * Email: KleaSCM@gmail.com
 */
```

### 4.5 - Public API Documentation
Exported functions may have documentation **ONLY** if the signature alone is insufficient to explain the behavior (e.g. side effects, error conditions).

---

## 5. Defensive Programming

### 5.1 - Assume All Input is Invalid
Validate everything. Never assume data from the outside world is correct.

### 5.2 - Avoid Global State
Only compile-time constants are permitted globally. All others must be local or injected.

### 5.3 - Separate Logic from Presentation
Do not include application logic in render functions or UI code.

---

## 6. Project Structure

### 6.1 - One Module or Component Per File
Each file should contain one logical unit. File name must match the exported symbol or type.

### 6.2 - Import Order Must Be Standard → Third-Party → Local
Insert a blank line between each section.

### 6.3 - No Circular Dependencies
Circular imports are always a violation. You must restructure to break the loop.

---

## 7. Testing

### 7.1 - Do Not Mock Internal Logic
Mocks are allowed only for boundary layers (e.g., APIs, file systems). Never mock internal domain logic.

### 7.2 - Document All Tests Clearly
Use clear, professional documentation to describe what the test intends.

### 7.3 - Avoid Snapshot Testing
Only allowed for UI rendering diffs or large structural comparisons with documented justification.

---

## 8. Tooling and CI Enforcement

### 8.1 - Linters and Formatters Are Mandatory
CI must block merges that fail lint or formatting checks.

| Language | Tools                    |
| -------- | ------------------------ |
| TS/TSX   | ESLint, Prettier         |
| C++      | clang-format, clang-tidy |
| Go       | gofmt, golint            |
| Rust     | rustfmt, Clippy          |

### 8.2 - Linter Configs Must Match This Style Guide
All rules described here (tabs, naming, line length, bracing) must be enforced.

---

## 9. Data Structures

### 9.1 - Prefer Arrays Over Sets
Arrays are the default for collections. Use [], Vec, std::vector, etc. unless proven otherwise.

### 9.2 - Set Usage is Strictly Gated
Use Set, HashSet, BTreeSet, etc. only when:
- Uniqueness is required for correctness
- .has() performance is proven
- Logic explicitly requires set semantics

### 9.3 - Justify Set Usage in Comments
Every use of a set must include a comment explaining why an array was insufficient.

```typescript
// Using Set here because duplicate entries would corrupt the sync state.
```

---

## 10. Prohibited Constructs

| Construct           | Reason                             |
| ------------------- | ---------------------------------- |
| Exceptions          | Unpredictable and unsafe           |
| snake_case          | Nonstandard, unaesthetic           |
| ALL_CAPS            | Aggressive, legacy                 |
| Global state        | Unsafe and fragile                 |
| JSX control logic   | Breaks UI separation model         |
| Inline control flow | Hurts readability and traceability |

### Clarification - Inline Control Flow
Inline control means using one-line flow control statements or ternary expressions that reduce clarity:

❌ **Not Allowed:**
```typescript
if (x) DoSomething();
return IsValid() ? "yes" : "no";
```

✅ **Use:**
```typescript
if (x) {
	DoSomething();
}

let result;
if (IsValid()) {
	result = "yes";
} else {
	result = "no";
}
```

---

## 11. Module Headers

### 11.1 - All Files Must Begin with a Header Block
Use a natural-language, prose-style doc block. Do not use @tags.

```typescript
/**
 * Command parser module.
 * 
 * Handles argument parsing, flag extraction, quote handling,
 * and shell-compatible input breaking.
 * 
 * Author: KleaSCM
 * Email: KleaSCM@gmail.com
 */
```

This applies to:
- .ts, .tsx
- .rs
- .cpp, .hpp
- .go
- Test files and modules too

---

## 12. Enforcement

### 12.1 - All Rules Are Binding
No team or engineer may override this guide without formal, documented approval. All infra and review must enforce it.

### 12.2 - Required in All Repositories
This file (StyleGuide.txt) must live in the repo root alongside .editorconfig and all tooling configs.

---

## .editorconfig

```ini
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = tab
indent_size = 4
max_line_length = 120
```