gh-cubical6-melly/skills/c4model-c4/code-element-identification.md

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/JavaScript
class ClassName { }
export class ClassName { }
abstract class ClassName { }
export default class ClassName { }

# Python
class ClassName:
    pass

class ClassName(ParentClass):
    pass

class ClassName(ABC):  # Abstract
    pass

// 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/JavaScript
function functionName() { }
export function functionName() { }
const functionName = () => { }
export const functionName = () => { }
export default function functionName() { }

# Python
def function_name():
    pass

// 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/JavaScript
async function functionName() { }
export async function functionName() { }
const functionName = async () => { }

# Python
async def function_name():
    pass

ID format: {component}-{function-name} Example: auth-service-authenticate

---

4. Methods

Detection patterns:

// TypeScript/JavaScript - inside class
class Example {
  methodName() { }
  async methodName() { }
  private methodName() { }
  static methodName() { }
  get propertyName() { }
  set propertyName(value) { }
}

# 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
interface InterfaceName { }
export interface InterfaceName { }
interface InterfaceName extends OtherInterface { }

// 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
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/JavaScript
const CONSTANT_NAME = 'value';
export const CONSTANT_NAME = 42;
export const CONFIG = { ... } as const;

# Python
CONSTANT_NAME = 'value'
MAX_RETRIES = 3

// 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
enum EnumName { A, B, C }
export enum EnumName { A = 'a', B = 'b' }
const enum EnumName { A, B, C }

# Python
from enum import Enum

class EnumName(Enum):
    A = 1
    B = 2

// Java
public enum EnumName { A, B, C }

ID format: {component}-{enum-name}-enum Example: auth-service-user-role-enum

---

9. Decorators

Detection patterns:

// TypeScript
function DecoratorName(target: any) { }
export function DecoratorName(): MethodDecorator { }

# 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

# 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