318 lines
8.9 KiB
Markdown
318 lines
8.9 KiB
Markdown
# Observation Guide for C4 Code Elements
|
||
|
||
This guide provides comprehensive methodology for documenting observations at the C4 Code level.
|
||
|
||
---
|
||
|
||
## Observation Categories
|
||
|
||
### 1. **implementation**
|
||
Code implementation patterns, algorithms, logic flow
|
||
|
||
**Examples:**
|
||
- "Uses async/await pattern for non-blocking database operations"
|
||
- "Implements retry logic with exponential backoff"
|
||
- "Uses memoization to cache expensive calculations"
|
||
- "Implements pagination with cursor-based navigation"
|
||
- "Uses builder pattern for complex object construction"
|
||
|
||
**Evidence types:** code, pattern
|
||
|
||
---
|
||
|
||
### 2. **error-handling**
|
||
Exception handling, error propagation, recovery mechanisms
|
||
|
||
**Examples:**
|
||
- "Generic catch block masks specific error types - consider typed error handling"
|
||
- "Custom error classes with proper error codes and stack traces"
|
||
- "Missing error handling for null/undefined cases"
|
||
- "Proper error boundary implementation with fallback UI"
|
||
- "Silently catches and ignores errors - may hide bugs"
|
||
|
||
**Evidence types:** code, pattern
|
||
|
||
---
|
||
|
||
### 3. **type-safety**
|
||
Type definitions, generics, type guards, null safety
|
||
|
||
**Examples:**
|
||
- "Uses strict null checks with proper type guards"
|
||
- "Generic function with proper type constraints"
|
||
- "Missing type annotation on public API - should be explicit"
|
||
- "Type narrowing with discriminated unions for safe handling"
|
||
- "Uses `any` type extensively - reduces type safety benefits"
|
||
|
||
**Evidence types:** code, pattern
|
||
|
||
---
|
||
|
||
### 4. **documentation**
|
||
JSDoc, docstrings, inline comments, API documentation
|
||
|
||
**Examples:**
|
||
- "Comprehensive JSDoc with @param, @returns, and @example"
|
||
- "Missing documentation for complex algorithm - add explanatory comments"
|
||
- "Inline comments explain business logic decisions"
|
||
- "API endpoint documentation includes request/response examples"
|
||
- "Outdated comments don't match current implementation"
|
||
|
||
**Evidence types:** documentation, code
|
||
|
||
---
|
||
|
||
### 5. **testing**
|
||
Test coverage, testability, mocking concerns
|
||
|
||
**Examples:**
|
||
- "90% test coverage with edge cases covered"
|
||
- "Hard to test due to static dependencies - consider dependency injection"
|
||
- "Proper use of dependency injection improves testability"
|
||
- "Missing tests for error paths and edge cases"
|
||
- "Test file exists but only covers happy path"
|
||
|
||
**Evidence types:** test, code
|
||
|
||
---
|
||
|
||
### 6. **complexity**
|
||
Cyclomatic complexity, cognitive complexity, nesting depth
|
||
|
||
**Examples:**
|
||
- "Cyclomatic complexity of 15 exceeds threshold (6) - extract methods"
|
||
- "Deep nesting (5 levels) reduces readability - use guard clauses"
|
||
- "Function has 8 parameters - consider parameter object pattern"
|
||
- "Method is 150 LOC - split into smaller focused functions"
|
||
- "Single method handles multiple responsibilities - violates SRP"
|
||
|
||
**Evidence types:** metric, code
|
||
|
||
---
|
||
|
||
### 7. **performance**
|
||
Algorithm efficiency, memory usage, async patterns
|
||
|
||
**Examples:**
|
||
- "O(n²) algorithm could be optimized to O(n log n)"
|
||
- "Memory leak: event listener not removed on cleanup"
|
||
- "Unnecessary database queries in loop - use batch query"
|
||
- "Proper use of lazy loading for large data sets"
|
||
- "Missing debounce on rapid event handler"
|
||
|
||
**Evidence types:** code, metric, pattern
|
||
|
||
---
|
||
|
||
### 8. **security**
|
||
Input validation, sanitization, authentication, authorization
|
||
|
||
**Examples:**
|
||
- "Missing input validation on user-provided data"
|
||
- "SQL query properly parameterized against injection"
|
||
- "Password stored with bcrypt hashing (cost factor 12)"
|
||
- "Sensitive data logged in debug output - security risk"
|
||
- "Authorization check missing before data access"
|
||
|
||
**Evidence types:** code, pattern
|
||
|
||
---
|
||
|
||
### 9. **concurrency**
|
||
Async/await, promises, race conditions, thread safety
|
||
|
||
**Examples:**
|
||
- "Potential race condition in concurrent state updates"
|
||
- "Proper use of Promise.all for parallel independent requests"
|
||
- "Missing await on async function call - returns Promise instead of value"
|
||
- "Deadlock potential with multiple lock acquisitions"
|
||
- "Uses mutex pattern for thread-safe resource access"
|
||
|
||
**Evidence types:** code, pattern
|
||
|
||
---
|
||
|
||
### 10. **patterns**
|
||
Design patterns, code patterns, anti-patterns
|
||
|
||
**Examples:**
|
||
- "Factory pattern used for creating validator instances"
|
||
- "God object anti-pattern - class has too many responsibilities"
|
||
- "Proper use of strategy pattern for payment processing"
|
||
- "Singleton pattern ensures single database connection pool"
|
||
- "Repository pattern cleanly separates data access concerns"
|
||
|
||
**Evidence types:** pattern, code
|
||
|
||
---
|
||
|
||
## Observation Structure
|
||
|
||
```json
|
||
{
|
||
"id": "obs-{element-id}-{category}-{number}",
|
||
"category": "implementation|error-handling|type-safety|documentation|testing|complexity|performance|security|concurrency|patterns",
|
||
"severity": "info|warning|critical",
|
||
"description": "Clear, actionable description of the observation",
|
||
"evidence": [
|
||
{
|
||
"location": "src/path/to/file.ts:45-67",
|
||
"type": "code|metric|pattern|test|documentation",
|
||
"snippet": "Optional relevant code snippet"
|
||
}
|
||
],
|
||
"tags": ["relevant", "searchable", "tags"]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Severity Guidelines
|
||
|
||
### ℹ️ info
|
||
Use for:
|
||
- Best practices being followed
|
||
- Interesting implementation details
|
||
- Documentation notes
|
||
- Positive observations
|
||
|
||
**Examples:**
|
||
- "Uses dependency injection for loose coupling"
|
||
- "Well-documented API with comprehensive JSDoc"
|
||
- "Implements singleton pattern correctly"
|
||
|
||
---
|
||
|
||
### ⚠️ warning
|
||
Use for:
|
||
- Potential issues that should be addressed
|
||
- Technical debt
|
||
- Performance concerns
|
||
- Missing tests
|
||
- Minor security considerations
|
||
|
||
**Examples:**
|
||
- "Cyclomatic complexity exceeds threshold"
|
||
- "Missing input validation on internal API"
|
||
- "No tests for edge cases"
|
||
- "Consider using more specific error types"
|
||
|
||
---
|
||
|
||
### 🔴 critical
|
||
Use for:
|
||
- Security vulnerabilities
|
||
- Breaking bugs
|
||
- Data loss potential
|
||
- Production-impacting issues
|
||
- Immediate action required
|
||
|
||
**Examples:**
|
||
- "SQL injection vulnerability - user input not sanitized"
|
||
- "Unhandled promise rejection crashes application"
|
||
- "Sensitive data exposed in logs"
|
||
- "Race condition causes data corruption"
|
||
|
||
---
|
||
|
||
## Evidence Types
|
||
|
||
| Type | Description | Example |
|
||
|------|-------------|---------|
|
||
| `code` | Code snippet or reference | `"snippet": "if (user.role === 'admin')"` |
|
||
| `metric` | Calculated metric value | Complexity score, LOC count |
|
||
| `pattern` | Design pattern identification | Factory, Singleton, Repository |
|
||
| `test` | Test file or coverage info | Test file location |
|
||
| `documentation` | Doc reference | JSDoc, README section |
|
||
|
||
---
|
||
|
||
## Complete Example
|
||
|
||
```json
|
||
{
|
||
"observations": [
|
||
{
|
||
"id": "obs-auth-service-security-01",
|
||
"category": "security",
|
||
"severity": "critical",
|
||
"description": "Password comparison uses timing-vulnerable equality check. Use constant-time comparison to prevent timing attacks.",
|
||
"evidence": [
|
||
{
|
||
"location": "src/services/auth.ts:78",
|
||
"type": "code",
|
||
"snippet": "if (password === storedPassword)"
|
||
}
|
||
],
|
||
"tags": ["security", "timing-attack", "authentication"]
|
||
},
|
||
{
|
||
"id": "obs-auth-service-patterns-01",
|
||
"category": "patterns",
|
||
"severity": "info",
|
||
"description": "Implements repository pattern for data access, providing clean separation between business logic and persistence.",
|
||
"evidence": [
|
||
{
|
||
"location": "src/services/auth.ts:15-20",
|
||
"type": "pattern"
|
||
}
|
||
],
|
||
"tags": ["repository-pattern", "clean-architecture"]
|
||
},
|
||
{
|
||
"id": "obs-auth-service-complexity-01",
|
||
"category": "complexity",
|
||
"severity": "warning",
|
||
"description": "Authenticate method has cyclomatic complexity of 12, exceeding recommended threshold of 6. Consider extracting validation and token generation into separate methods.",
|
||
"evidence": [
|
||
{
|
||
"location": "src/services/auth.ts:45-120",
|
||
"type": "metric"
|
||
}
|
||
],
|
||
"tags": ["complexity", "refactoring-candidate"]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Writing Good Observations
|
||
|
||
### ✅ DO:
|
||
- Be specific and actionable
|
||
- Include exact file paths and line numbers
|
||
- Provide code snippets for context
|
||
- Use appropriate severity levels
|
||
- Include relevant tags for searchability
|
||
- Suggest fixes for warnings/critical issues
|
||
|
||
### ❌ DON'T:
|
||
- Be vague ("code is complex")
|
||
- Skip evidence
|
||
- Overuse critical severity
|
||
- Write observations without actionable insight
|
||
- Forget to tag important categories
|
||
- Mix multiple issues in one observation
|
||
|
||
---
|
||
|
||
## Tags Reference
|
||
|
||
Common useful tags:
|
||
|
||
**Architecture:** `clean-architecture`, `hexagonal`, `layered`, `microservices`
|
||
|
||
**Patterns:** `singleton`, `factory`, `repository`, `strategy`, `observer`, `decorator`
|
||
|
||
**Anti-patterns:** `god-object`, `spaghetti-code`, `magic-numbers`, `primitive-obsession`
|
||
|
||
**Quality:** `refactoring-candidate`, `technical-debt`, `needs-review`
|
||
|
||
**Security:** `input-validation`, `authentication`, `authorization`, `sql-injection`, `xss`
|
||
|
||
**Performance:** `n-plus-one`, `memory-leak`, `optimization-candidate`
|
||
|
||
**Testing:** `needs-tests`, `integration-test`, `unit-test`, `edge-cases`
|