344 lines
6.5 KiB
Markdown
344 lines
6.5 KiB
Markdown
# Code Element Identification Methodology
|
|
|
|
This guide provides comprehensive methodology for identifying code elements at the C4 (Code) level of the C4 Model.
|
|
|
|
---
|
|
|
|
## Code Element Types
|
|
|
|
### 1. Classes
|
|
|
|
**Detection patterns:**
|
|
```typescript
|
|
// TypeScript/JavaScript
|
|
class ClassName { }
|
|
export class ClassName { }
|
|
abstract class ClassName { }
|
|
export default class ClassName { }
|
|
```
|
|
|
|
```python
|
|
# Python
|
|
class ClassName:
|
|
pass
|
|
|
|
class ClassName(ParentClass):
|
|
pass
|
|
|
|
class ClassName(ABC): # Abstract
|
|
pass
|
|
```
|
|
|
|
```java
|
|
// Java
|
|
public class ClassName { }
|
|
public abstract class ClassName { }
|
|
public final class ClassName { }
|
|
```
|
|
|
|
**ID format:** `{component}-{class-name}-class`
|
|
**Example:** `auth-service-user-manager-class`
|
|
|
|
---
|
|
|
|
### 2. Functions
|
|
|
|
**Detection patterns:**
|
|
```typescript
|
|
// TypeScript/JavaScript
|
|
function functionName() { }
|
|
export function functionName() { }
|
|
const functionName = () => { }
|
|
export const functionName = () => { }
|
|
export default function functionName() { }
|
|
```
|
|
|
|
```python
|
|
# Python
|
|
def function_name():
|
|
pass
|
|
```
|
|
|
|
```java
|
|
// Java - methods are always in classes
|
|
public static void functionName() { }
|
|
```
|
|
|
|
**ID format:** `{component}-{function-name}`
|
|
**Example:** `auth-service-validate-token`
|
|
|
|
---
|
|
|
|
### 3. Async Functions
|
|
|
|
**Detection patterns:**
|
|
```typescript
|
|
// TypeScript/JavaScript
|
|
async function functionName() { }
|
|
export async function functionName() { }
|
|
const functionName = async () => { }
|
|
```
|
|
|
|
```python
|
|
# Python
|
|
async def function_name():
|
|
pass
|
|
```
|
|
|
|
**ID format:** `{component}-{function-name}`
|
|
**Example:** `auth-service-authenticate`
|
|
|
|
---
|
|
|
|
### 4. Methods
|
|
|
|
**Detection patterns:**
|
|
```typescript
|
|
// TypeScript/JavaScript - inside class
|
|
class Example {
|
|
methodName() { }
|
|
async methodName() { }
|
|
private methodName() { }
|
|
static methodName() { }
|
|
get propertyName() { }
|
|
set propertyName(value) { }
|
|
}
|
|
```
|
|
|
|
```python
|
|
# Python
|
|
class Example:
|
|
def method_name(self):
|
|
pass
|
|
|
|
@classmethod
|
|
def class_method(cls):
|
|
pass
|
|
|
|
@staticmethod
|
|
def static_method():
|
|
pass
|
|
```
|
|
|
|
**ID format:** `{class-id}-{method-name}`
|
|
**Example:** `auth-service-class-get-user`
|
|
|
|
---
|
|
|
|
### 5. Interfaces
|
|
|
|
**Detection patterns:**
|
|
```typescript
|
|
// TypeScript
|
|
interface InterfaceName { }
|
|
export interface InterfaceName { }
|
|
interface InterfaceName extends OtherInterface { }
|
|
```
|
|
|
|
```java
|
|
// Java
|
|
public interface InterfaceName { }
|
|
public interface InterfaceName extends OtherInterface { }
|
|
```
|
|
|
|
**ID format:** `{component}-{interface-name}-interface`
|
|
**Example:** `auth-service-i-user-repository-interface`
|
|
|
|
---
|
|
|
|
### 6. Types
|
|
|
|
**Detection patterns:**
|
|
```typescript
|
|
// TypeScript
|
|
type TypeName = string | number;
|
|
export type TypeName = { field: string };
|
|
type TypeName<T> = T[];
|
|
type TypeName = Pick<OtherType, 'field'>;
|
|
```
|
|
|
|
**ID format:** `{component}-{type-name}-type`
|
|
**Example:** `auth-service-user-credentials-type`
|
|
|
|
---
|
|
|
|
### 7. Constants
|
|
|
|
**Detection patterns:**
|
|
```typescript
|
|
// TypeScript/JavaScript
|
|
const CONSTANT_NAME = 'value';
|
|
export const CONSTANT_NAME = 42;
|
|
export const CONFIG = { ... } as const;
|
|
```
|
|
|
|
```python
|
|
# Python
|
|
CONSTANT_NAME = 'value'
|
|
MAX_RETRIES = 3
|
|
```
|
|
|
|
```java
|
|
// Java
|
|
public static final String CONSTANT_NAME = "value";
|
|
public static final int MAX_RETRIES = 3;
|
|
```
|
|
|
|
**ID format:** `{component}-{constant-name}-const`
|
|
**Example:** `auth-service-max-login-attempts-const`
|
|
|
|
---
|
|
|
|
### 8. Enums
|
|
|
|
**Detection patterns:**
|
|
```typescript
|
|
// TypeScript
|
|
enum EnumName { A, B, C }
|
|
export enum EnumName { A = 'a', B = 'b' }
|
|
const enum EnumName { A, B, C }
|
|
```
|
|
|
|
```python
|
|
# Python
|
|
from enum import Enum
|
|
|
|
class EnumName(Enum):
|
|
A = 1
|
|
B = 2
|
|
```
|
|
|
|
```java
|
|
// Java
|
|
public enum EnumName { A, B, C }
|
|
```
|
|
|
|
**ID format:** `{component}-{enum-name}-enum`
|
|
**Example:** `auth-service-user-role-enum`
|
|
|
|
---
|
|
|
|
### 9. Decorators
|
|
|
|
**Detection patterns:**
|
|
```typescript
|
|
// TypeScript
|
|
function DecoratorName(target: any) { }
|
|
export function DecoratorName(): MethodDecorator { }
|
|
```
|
|
|
|
```python
|
|
# Python
|
|
def decorator_name(func):
|
|
def wrapper(*args, **kwargs):
|
|
return func(*args, **kwargs)
|
|
return wrapper
|
|
```
|
|
|
|
**ID format:** `{component}-{decorator-name}-decorator`
|
|
**Example:** `auth-service-authenticated-decorator`
|
|
|
|
---
|
|
|
|
## Significance Criteria
|
|
|
|
Only document a code element if **ANY** of these apply:
|
|
|
|
### Public API
|
|
- Exported from module
|
|
- Part of public interface
|
|
- Used by external callers
|
|
|
|
### Complexity
|
|
- Lines of code > 20
|
|
- Cyclomatic complexity > 4
|
|
- Cognitive complexity > 10
|
|
|
|
### Architecture
|
|
- Implements design pattern
|
|
- Key abstraction or facade
|
|
- Entry point or controller action
|
|
|
|
### Business Logic
|
|
- Contains critical business rules
|
|
- Handles sensitive data
|
|
- Has security implications
|
|
|
|
### Dependencies
|
|
- Multiple callers (> 2)
|
|
- Multiple dependencies (> 3)
|
|
- Central to component
|
|
|
|
---
|
|
|
|
## Detection Commands
|
|
|
|
```bash
|
|
# TypeScript - Find classes
|
|
grep -rn "^export class\|^class " src/ --include="*.ts"
|
|
|
|
# TypeScript - Find functions
|
|
grep -rn "^export function\|^export async function\|^export const.*=.*=>" src/ --include="*.ts"
|
|
|
|
# TypeScript - Find interfaces
|
|
grep -rn "^export interface\|^interface " src/ --include="*.ts"
|
|
|
|
# TypeScript - Find types
|
|
grep -rn "^export type\|^type " src/ --include="*.ts"
|
|
|
|
# TypeScript - Find enums
|
|
grep -rn "^export enum\|^enum " src/ --include="*.ts"
|
|
|
|
# Python - Find classes
|
|
grep -rn "^class " src/ --include="*.py"
|
|
|
|
# Python - Find functions
|
|
grep -rn "^def \|^async def " src/ --include="*.py"
|
|
|
|
# Count lines per file
|
|
wc -l src/**/*.ts | sort -n
|
|
```
|
|
|
|
---
|
|
|
|
## Naming Conventions
|
|
|
|
### ID Format
|
|
- Use kebab-case
|
|
- Include component prefix
|
|
- Include element type suffix where helpful
|
|
- Pattern: `{component-id}-{element-name}[-{type}]`
|
|
|
|
### Name Field
|
|
- Preserve original case (PascalCase, camelCase, snake_case)
|
|
- Use exact name from source code
|
|
|
|
### Examples
|
|
|
|
| Source Name | ID | name |
|
|
|------------|-----|------|
|
|
| `UserService` | `auth-user-service-class` | `UserService` |
|
|
| `authenticate` | `auth-authenticate` | `authenticate` |
|
|
| `IUserRepository` | `auth-i-user-repository-interface` | `IUserRepository` |
|
|
| `LoginCredentials` | `auth-login-credentials-type` | `LoginCredentials` |
|
|
| `MAX_RETRIES` | `auth-max-retries-const` | `MAX_RETRIES` |
|
|
| `UserRole` | `auth-user-role-enum` | `UserRole` |
|
|
|
|
---
|
|
|
|
## Best Practices
|
|
|
|
### ✅ DO:
|
|
- Focus on significant, public elements
|
|
- Use consistent ID naming
|
|
- Preserve original casing in name field
|
|
- Document all public API elements
|
|
- Include classes that define key abstractions
|
|
|
|
### ❌ DON'T:
|
|
- Document every private helper function
|
|
- Document trivial getters/setters
|
|
- Document test files as code elements
|
|
- Use file names as element IDs
|
|
- Skip exported functions/classes
|