Code Organization & Structure

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

// ❌ Poor variable names
const d = new Date();
const arr = users.filter(u => u.a);
const flag = order.total > 100;
const temp = calculateDiscount(price);
const data = fetchUserData(userId);
 
// ✅ Intention-revealing variable names
const orderCreatedDate = new Date();
const activeUsers = users.filter(user => user.isActive);
const qualifiesForDiscount = order.total > 100;
const discountAmount = calculateDiscount(price);
const userProfile = fetchUserData(userId);
 
// ❌ Inconsistent boolean naming
const active = true;        // Is it active now? Should be active?
const disabled = false;     // Negatives are confusing
const status = true;        // Status of what?
 
// ✅ Boolean as yes/no questions
const isActive = true;           // Clear: currently active
const isEnabled = true;          // Clear: avoiding double negative
const hasValidSubscription = true;  // Clear: possession check
const canAccessAdminPanel = true;   // Clear: capability check
const shouldRetryConnection = true; // Clear: decision indicator

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

// ❌ Vague or misleading function names
function process(order: Order): void { }     // Process how?
function handle(data: any): any { }          // Handle what?
function doStuff(): void { }                 // No information at all
function orderFunc(o: Order): number { }     // Type in name, unclear purpose
 
// ✅ Clear, intention-revealing function names
function submitOrderForFulfillment(order: Order): void { }
function parseJsonConfigFile(data: string): Config { }
function calculateOrderTotalWithTax(order: Order): number { }
 
// ❌ Get/set misuse
function getUser(name: string): void {       // 'get' but returns void - actually creates
    this.user = new User(name);
}
 
// ✅ Accurate verb usage
function createAndStoreUser(name: string): void {
    this.user = new User(name);
}
 
// ❌ Inconsistent boolean method naming
function checkValid(): boolean { }           // 'check' is vague
function valid(): boolean { }                // Adjective, not verb phrase
function validateOrder(): boolean { }        // validate usually implies throwing
 
// ✅ Boolean methods as questions
function isValid(): boolean { }
function hasValidationErrors(): boolean { }
function canBeProcessed(): boolean { }
 
// Side effect clarity
function ensureDirectoryExists(path: string): void { }    // May create if missing
function validateOrThrow(input: Input): void { }          // Throws on invalid
function findOrCreate(id: string): Entity { }             // May create new

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

// ❌ Poor class names
class Manager { }           // Manager of what?
class Helper { }            // Vague, god-class risk
class Utility { }           // Bag of unrelated functions
class Data { }              // What kind of data?
class Info { }              // Information about what?
 
// ✅ Specific, meaningful class names
class OrderFulfillmentManager { }
class PasswordHashingService { }
class ShippingCostCalculator { }
class CustomerAccountData { }
class ProductCatalogInfo { }
 
// Interface naming approaches
 
// Approach 1: Capability-based (preferred in TypeScript)
interface Serializable {
    serialize(): string;
}
interface Observable<T> {
    subscribe(observer: Observer<T>): Subscription;
}
 
// Approach 2: Role-based
interface OrderRepository {
    findById(id: string): Promise<Order | null>;
    save(order: Order): Promise<void>;
}
interface PaymentGateway {
    authorize(payment: Payment): Promise<AuthResult>;
    capture(authorizationId: string): Promise<CaptureResult>;
}
 
// Approach 3: Contract suffix (less common, but explicit)
interface UserServiceContract {
    getUser(id: string): Promise<User>;
}
 
// Implementation naming
class PostgresOrderRepository implements OrderRepository { }
class StripePaymentGateway implements PaymentGateway { }
class InMemoryOrderRepository implements OrderRepository { }  // Test double

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

// Constants: SCREAMING_SNAKE_CASE is traditional
const MAX_RETRY_ATTEMPTS = 3;
const DEFAULT_TIMEOUT_MS = 5000;
const HTTP_STATUS_OK = 200;
const API_BASE_URL = 'https://api.example.com';
 
// Alternative: PascalCase or camelCase for object constants
const DatabaseConfig = {
    host: 'localhost',
    port: 5432,
    maxConnections: 10,
} as const;
 
// Enums: PascalCase for enum name, UPPER_CASE or PascalCase for values
enum OrderStatus {
    PENDING = 'PENDING',
    CONFIRMED = 'CONFIRMED', 
    SHIPPED = 'SHIPPED',
    DELIVERED = 'DELIVERED',
    CANCELLED = 'CANCELLED',
}
 
// Alternative enum style (PascalCase values)
enum PaymentMethod {
    CreditCard = 'credit_card',
    DebitCard = 'debit_card',
    BankTransfer = 'bank_transfer',
    DigitalWallet = 'digital_wallet',
}
 
// Union types as alternative to enums
type Priority = 'low' | 'medium' | 'high' | 'urgent';
type Direction = 'north' | 'south' | 'east' | 'west';
 
// ❌ Poor constant naming
const MAX = 100;           // Max what?
const TIMEOUT = 5000;      // In what units?
const ERROR = -1;          // Which error?
const FLAG = true;         // Meaningless
 
// ✅ Descriptive constant naming  
const MAX_ITEMS_PER_PAGE = 100;
const CONNECTION_TIMEOUT_MILLISECONDS = 5000;
const ERROR_CODE_INVALID_INPUT = -1;
const FEATURE_FLAG_DARK_MODE_ENABLED = true;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# Package/directory naming patterns
 
# ❌ Poor package names
src/
├── stuff/              # Meaningless
├── helpers/            # Vague grab-bag
├── misc/               # Undefined scope
└── code/               # Redundant
 
# ✅ Descriptive package names
src/
├── orders/             # Order domain (noun = domain)
├── authentication/     # Auth capability (noun = capability)
├── payments/           # Payment processing
└── notifications/      # Notification services
 
# File naming within packages (TypeScript example)
src/orders/
├── Order.ts                    # Domain entity
├── OrderService.ts             # Business logic
├── OrderRepository.ts          # Data access
├── OrderController.ts          # HTTP handlers
├── order-types.ts              # Type definitions (kebab-case for non-class files)
├── order.constants.ts          # Constants
├── order.errors.ts             # Custom errors
├── __tests__/
│   ├── OrderService.test.ts
│   └── OrderRepository.test.ts
└── index.ts                    # Public API exports