System Design (LLD)Code Organization & Structure

Code Organization & Structure

LevelIntermediate

Duration75 mins

TopicCode Organization & Structure

4 / 4

Code Layout Best Practices

The Visual Dimension of Code

Code is read far more often than it's written. Studies suggest developers spend 10-20 times more time reading code than writing it. This reality has a profound implication: the visual layout of code—how we arrange elements within files—directly impacts productivity.

Code layout encompasses decisions like:

How do we order members within a class?
When should we use blank lines?
How do we format complex expressions?
What should appear at the top of a file vs. the bottom?
How do we group related functionality?

These might seem like minor aesthetic preferences, but they accumulate. A codebase with consistent, thoughtful layout is dramatically easier to navigate and understand. A codebase with inconsistent or poor layout creates constant friction—small annoyances that compound into significant cognitive overhead.

What You Will Learn

By the end of this page, you will understand the principles behind effective code layout, master the conventions for ordering class members, learn when and how to use whitespace for clarity, and develop habits that make code visually scannable and easy to navigate.

Why Layout Matters

Layout isn't about making code 'pretty'—it's about making code scannable. Developers rarely read code line by line like a novel; they scan, looking for landmarks, patterns, and relevant sections. Good layout supports this scanning behavior.

How Layout Affects Development

•Scanning speed — Consistent ordering means developers know where to look. Public methods at the top? Always. Private helpers at the bottom? Guaranteed. This predictability accelerates navigation.
•Pattern recognition — Visual similarity signals logical similarity. When related methods are grouped and formatted consistently, the eye can quickly identify patterns.
•Error detection — Formatting inconsistencies often signal logic errors. A misaligned brace or an extra/missing blank line can indicate something went wrong during editing.
•Merge conflict prevention — Consistent formatting reduces spurious diff noise. When everyone formats the same way, diffs show only meaningful changes.
•Cognitive load reduction — When layout is predictable, the brain doesn't spend energy parsing structure. That energy goes to understanding logic.

❌ Inconsistent, hard-to-scan layout:

class OrderService {
private repo: OrderRepository;
public async getOrder(id: string) {
const order = await this.repo.find(id);
if (!order) { throw new NotFoundError(); }
return order;
}
constructor(repo: OrderRepository) {
this.repo = repo;
}
public async createOrder(data: CreateOrderData) {
const order = new Order(data);
await this.repo.save(order);
return order;
}
private validate(data: any): boolean {
return data.items?.length > 0;
}
}

No visual structure. Constructor in the middle. Private/public mixed.

✅ Clean, scannable layout:

class OrderService {
    private repo: OrderRepository;

    constructor(repo: OrderRepository) {
        this.repo = repo;
    }

    // --- Public API ---
    
    public async getOrder(id: string) {
        const order = await this.repo.find(id);
        if (!order) {
            throw new NotFoundError();
        }
        return order;
    }

    public async createOrder(data: CreateOrderData) {
        const order = new Order(data);
        await this.repo.save(order);
        return order;
    }

    // --- Private Helpers ---
    
    private validate(data: any): boolean {
        return data.items?.length > 0;
    }
}

Clear sections. Predictable ordering. Easy to scan.

The Newspaper Metaphor

Robert C. Martin's 'newspaper metaphor': a file should read like a newspaper article. The most important, high-level information (public API) comes first—the headline. Details follow in descending order of importance. Readers can stop at any point and have a complete picture at that level of detail.

Class Member Ordering

How you order members within a class significantly impacts readability. There are two dominant philosophies, each with merits:

Class Member Ordering Approaches
Approach	Order	Rationale
Visibility-first	Public → Protected → Private (within each: static → instance → constructor → methods → fields)	Most important (public API) visible first; implementation details hidden below
Member-type-first	Fields → Constructor → Methods (within each: static → instance → public → private)	Logical flow: initialization before behavior; state before operations

Recommended Class 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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
/**
 * OrderService - Handles order lifecycle operations
 * 
 * Standard class structure: visibility-first ordering
 */
class OrderService {
    // ==========================================
    // 1. STATIC MEMBERS (if any)
    // ==========================================
    private static readonly DEFAULT_PAGE_SIZE = 20;
 
    // ==========================================
    // 2. INSTANCE FIELDS
    // ==========================================
    private readonly repository: OrderRepository;
    private readonly eventBus: EventBus;
    private readonly logger: Logger;
 
    // ==========================================
    // 3. CONSTRUCTOR
    // ==========================================
    constructor(
        repository: OrderRepository,
        eventBus: EventBus,
        logger: Logger
    ) {
        this.repository = repository;
        this.eventBus = eventBus;
        this.logger = logger;
    }
 
    // ==========================================
    // 4. PUBLIC METHODS (the class's API)
    // ==========================================
    
    /**
     * Retrieves an order by ID
     * @throws NotFoundError if order doesn't exist
     */
    public async getOrder(orderId: string): Promise<Order> {
        this.logger.debug(`Fetching order ${orderId}`);
        
        const order = await this.repository.findById(orderId);
        if (!order) {
            throw new NotFoundError(`Order ${orderId} not found`);
        }
        
        return order;
    }
 
    /**
     * Creates a new order from the given data
     */
    public async createOrder(data: CreateOrderData): Promise<Order> {
        this.validateOrderData(data);
        
        const order = this.buildOrder(data);
        await this.repository.save(order);
        
        await this.eventBus.publish(new OrderCreatedEvent(order));
        
        return order;
    }
 
    /**
     * Lists orders with pagination
     */
    public async listOrders(options: ListOptions = {}): Promise<PaginatedResult<Order>> {
        const pageSize = options.pageSize ?? OrderService.DEFAULT_PAGE_SIZE;
        return this.repository.findAll({ ...options, pageSize });
    }
 
    // ==========================================
    // 5. PRIVATE METHODS (implementation details)
    // ==========================================
    
    private validateOrderData(data: CreateOrderData): void {
        if (!data.items || data.items.length === 0) {
            throw new ValidationError('Order must have at least one item');
        }
        
        if (!data.customerId) {
            throw new ValidationError('Customer ID is required');
        }
    }
 
    private buildOrder(data: CreateOrderData): Order {
        return new Order({
            id: generateId(),
            customerId: data.customerId,
            items: data.items,
            status: OrderStatus.PENDING,
            createdAt: new Date(),
        });
    }
}

Consistency Over Preference

Both ordering approaches are valid. What matters is consistency: all classes in a project should follow the same ordering convention. Many teams enforce this with linters (ESLint's member-ordering rule, Checkstyle's DeclarationOrder, etc.).

Vertical Spacing and Logical Grouping

Blank lines are paragraph breaks in code. They separate logical units and signal transitions in thought. Used well, they make code far more scannable. Used poorly (or not at all), code becomes a wall of text.

Vertical Spacing Guidelines

•One blank line between methods — Separates distinct units of behavior. This is non-negotiable.
•One blank line between logical sections within a method — Separate setup from logic from cleanup.
•Two blank lines between major sections — Between class declarations, between imports and class, between groups of related methods.
•No blank lines within tightly coupled code — Lines that work together to achieve one small goal should stay together.
•Blank line after control structure blocks — After if/for/while blocks, a blank line separates the next thought.

Effective Vertical Spacing
TypeScript
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
// ❌ No vertical spacing - hard to read
async function processOrder(orderId: string): Promise<void> {
    const order = await this.orderRepo.findById(orderId);
    if (!order) {
        throw new NotFoundError('Order not found');
    }
    const customer = await this.customerRepo.findById(order.customerId);
    if (!customer) {
        throw new NotFoundError('Customer not found');
    }
    const paymentResult = await this.paymentService.charge(customer, order.total);
    if (!paymentResult.success) {
        await this.orderRepo.updateStatus(orderId, 'PAYMENT_FAILED');
        throw new PaymentError(paymentResult.message);
    }
    await this.orderRepo.updateStatus(orderId, 'PAID');
    await this.notificationService.sendConfirmation(customer.email, order);
    await this.inventoryService.reserve(order.items);
}
 
// ✅ Logical grouping with blank lines
async function processOrder(orderId: string): Promise<void> {
    // Fetch required entities
    const order = await this.orderRepo.findById(orderId);
    if (!order) {
        throw new NotFoundError('Order not found');
    }
    
    const customer = await this.customerRepo.findById(order.customerId);
    if (!customer) {
        throw new NotFoundError('Customer not found');
    }
 
    // Process payment
    const paymentResult = await this.paymentService.charge(customer, order.total);
    if (!paymentResult.success) {
        await this.orderRepo.updateStatus(orderId, 'PAYMENT_FAILED');
        throw new PaymentError(paymentResult.message);
    }
 
    // Update state and notify
    await this.orderRepo.updateStatus(orderId, 'PAID');
    await this.notificationService.sendConfirmation(customer.email, order);
    await this.inventoryService.reserve(order.items);
}

The paragraph principle:

Think of blank lines as paragraph breaks in prose. Just as a paragraph groups related sentences, a code 'paragraph' groups related statements. When the thought changes—new validation, new operation, new phase—start a new paragraph.

Signs you need a blank line:

You're moving from setup to actual work
You're changing what entity you're operating on
A comment would be appropriate (instead of comment, use blank line + code paragraph)
You've finished one complete mini-task within a larger function

Avoid Excessive Blank Lines

While blank lines are valuable, too many fragment the code. Multiple consecutive blank lines or blank lines between every statement make code feel disconnected and wasteful of screen space. One blank line is almost always sufficient.

Horizontal Formatting

Horizontal layout involves indentation, line length, alignment, and spacing within lines. These choices affect how easily the eye can follow code structure.

Horizontal Formatting Guidelines
Aspect	Guideline	Rationale
Line length	80-120 characters max	Prevents horizontal scrolling; multiple files side-by-side
Indentation	2 or 4 spaces (consistent)	Shows nesting hierarchy; tabs vs spaces - pick one
Operator spacing	Space around binary operators	`a + b` not `a+b`; improves readability
Comma spacing	Space after commas	`fn(a, b, c)` not `fn(a,b,c)`
Alignment	Avoid excessive alignment	Aligned code requires maintenance; changes cascade

Horizontal Formatting Examples
TypeScript
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
// ❌ Line too long - requires horizontal scrolling
const result = await this.orderService.createOrder({ customerId: customer.id, items: cart.items, shippingAddress: customer.defaultAddress, billingAddress: customer.billingAddress, paymentMethod: customer.preferredPayment });
 
// ✅ Broken across lines for readability
const result = await this.orderService.createOrder({
    customerId: customer.id,
    items: cart.items,
    shippingAddress: customer.defaultAddress,
    billingAddress: customer.billingAddress,
    paymentMethod: customer.preferredPayment,
});
 
// ❌ Over-aligned - hard to maintain
const name        = 'John';
const email       = 'john@example.com';
const phoneNumber = '555-1234';
const address     = '123 Main St';
 
// ✅ Simple, consistent formatting
const name = 'John';
const email = 'john@example.com';
const phoneNumber = '555-1234';
const address = '123 Main St';
 
// ❌ Cramped expressions
const total=price*quantity+tax-discount;
if(order.status==='pending'&&order.items.length>0){
 
// ✅ Spaced for clarity
const total = price * quantity + tax - discount;
if (order.status === 'pending' && order.items.length > 0) {
 
// Long conditions - break for readability
// ❌ Hard to parse
if (user.isActive && user.hasPermission('admin') && user.department === 'engineering' && !user.isOnLeave) {
 
// ✅ Each condition on its own line
if (
    user.isActive &&
    user.hasPermission('admin') &&
    user.department === 'engineering' &&
    !user.isOnLeave
) {
    // ...
}

Use Formatters Religiously

Automatic formatters (Prettier, Black, gofmt, rustfmt) eliminate formatting debates and ensure consistency. Configure them in your project and run on save. Never commit unformatted code. The formatter's style becomes 'correct' by definition.

File Organization

A well-organized file follows a predictable structure from top to bottom. Readers should be able to navigate based on expectations about where things are.

Standard File Organization (TypeScript)
TypeScript
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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
// =====================================================
// 1. FILE HEADER (optional - auto-generated license, etc.)
// =====================================================
/**
 * OrderService.ts
 * 
 * Handles order lifecycle including creation, processing, and fulfillment.
 */
 
// =====================================================
// 2. IMPORTS - organized by category
// =====================================================
 
// External dependencies (node_modules)
import { Injectable } from '@nestjs/common';
import { v4 as uuid } from 'uuid';
 
// Internal absolute imports (project modules)
import { Logger } from '@/infrastructure/logging';
import { EventBus } from '@/infrastructure/events';
 
// Relative imports (same module/feature)
import { Order, OrderStatus } from './Order';
import { OrderRepository } from './OrderRepository';
import { CreateOrderData, OrderDTO } from './order.types';
 
// =====================================================
// 3. TYPE DEFINITIONS (if local to this file)
// =====================================================
 
interface ProcessingResult {
    success: boolean;
    orderId: string;
    message?: string;
}
 
// =====================================================
// 4. CONSTANTS (file-level)
// =====================================================
 
const MAX_ITEMS_PER_ORDER = 100;
const DEFAULT_PROCESSING_TIMEOUT_MS = 30000;
 
// =====================================================
// 5. MAIN CLASS/FUNCTION EXPORTS
// =====================================================
 
@Injectable()
export class OrderService {
    // ... class implementation
}
 
// =====================================================
// 6. HELPER FUNCTIONS (if not in separate file)
// =====================================================
 
function validateItemCount(items: OrderItem[]): void {
    if (items.length > MAX_ITEMS_PER_ORDER) {
        throw new ValidationError(`Cannot exceed ${MAX_ITEMS_PER_ORDER} items`);
    }
}
 
// =====================================================
// 7. DEFAULT EXPORT (if applicable)
// =====================================================
 
export default OrderService;

Import Organization Guidelines

•Group imports by source — External packages → Internal absolute → Relative imports. Separate groups with blank lines.
•Alphabetize within groups — Makes finding specific imports easier; many formatters do this automatically.
•Avoid wildcard imports — import * as foo obscures what's actually used; makes tree-shaking less effective.
•Keep imports minimal — Only import what you use. Some linters (eslint-plugin-unused-imports) can auto-remove unused imports.
•Consider barrel imports carefully — import { A, B, C } from './index' can cause circular dependency issues and bundle bloat.

One Export Per File

While not universal, many teams adopt a 'one class/function per file' rule. This simplifies file naming (file name matches export), makes responsibility clear, and prevents files from growing too large. Helper functions tightly coupled to the main export can stay in the same file.

Function and Method Layout

Within functions, layout affects how easily readers can follow the logic. The key principle: keep related code together, and separate distinct phases.

Function Layout Patterns
TypeScript
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
46
47
// Well-structured function layout
async function processOrderSubmission(
    orderId: string,
    paymentDetails: PaymentDetails
): Promise<OrderConfirmation> {
    // Phase 1: Validation and early returns (guard clauses)
    const order = await this.orderRepo.findById(orderId);
    if (!order) {
        throw new NotFoundError(`Order ${orderId} not found`);
    }
    
    if (order.status !== OrderStatus.PENDING) {
        throw new InvalidStateError(`Cannot process order in ${order.status} state`);
    }
 
    // Phase 2: Gather required data
    const customer = await this.customerRepo.findById(order.customerId);
    const inventory = await this.inventoryService.checkAvailability(order.items);
    
    if (!inventory.allAvailable) {
        throw new InsufficientInventoryError(inventory.unavailableItems);
    }
 
    // Phase 3: Core business logic
    const paymentResult = await this.paymentService.processPayment({
        customerId: customer.id,
        amount: order.total,
        ...paymentDetails,
    });
 
    if (!paymentResult.success) {
        await this.handlePaymentFailure(order, paymentResult);
        throw new PaymentFailedError(paymentResult.errorMessage);
    }
 
    // Phase 4: Update state
    order.markAsPaid(paymentResult.transactionId);
    await this.orderRepo.save(order);
    
    // Phase 5: Side effects (notifications, events)
    await this.inventoryService.reserveItems(order.items);
    await this.eventBus.publish(new OrderPaidEvent(order));
    await this.notificationService.sendConfirmation(customer.email, order);
 
    // Phase 6: Return result
    return this.buildOrderConfirmation(order, paymentResult);
}

Function Layout Principles

•Guard clauses first — Handle invalid inputs and edge cases at the top. Return early. This keeps the 'happy path' at the lowest indentation level.
•Declare variables close to use — Don't declare all variables at the top of the function (old C style). Declare when first needed.
•Group related operations — Lines that work together should be adjacent. Separate groups with blank lines.
•Single level of abstraction — A function's statements should be at the same abstraction level. Don't mix high-level orchestration with low-level details.
•The step-down rule — Functions called by a function should appear below it. Reading top-to-bottom follows the call hierarchy.

Extract Phases to Functions

If your function has clear phases (as in the example above), consider extracting each phase to a separate function. This makes the high-level flow explicit: validate(), gatherData(), processPayment(), updateState(), notifyParties(). The main function becomes a readable orchestration.

Comments and Documentation Layout

Comments are part of code layout. When and how to use them significantly affects readability. The goal: comments should add value, not restate the obvious.

When to Use Comments
Comment Type	Purpose	Example
JSDoc/Javadoc	Public API documentation	Parameters, return values, exceptions
Why comments	Explain non-obvious decisions	Why this algorithm, not another
Warning comments	Alert to potential issues	Performance implications, side effects
TODO/FIXME	Track technical debt	Known issues, planned improvements
Section markers	Delineate major sections	// --- Public API ---

Effective vs Ineffective Comments
TypeScript
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
46
47
48
49
50
51
52
53
54
// ❌ USELESS COMMENTS - Restate the obvious
// Increment counter
counter++;
 
// Check if user is active
if (user.isActive) { }
 
// Loop through items
for (const item of items) { }
 
// Constructor
constructor() { }
 
 
// ✅ VALUABLE COMMENTS - Add information not in the code
 
/**
 * Calculates compound interest using the standard formula.
 * 
 * @param principal - Initial investment amount
 * @param rate - Annual interest rate as decimal (e.g., 0.05 for 5%)
 * @param timesCompounded - Number of times interest compounds per year
 * @param years - Investment duration in years
 * @returns The final amount including principal and interest
 * 
 * @example
 * // $1000 at 5% compounded monthly for 10 years
 * calculateCompoundInterest(1000, 0.05, 12, 10) // Returns $1647.01
 */
function calculateCompoundInterest(
    principal: number,
    rate: number, 
    timesCompounded: number,
    years: number
): number {
    // Standard compound interest formula: A = P(1 + r/n)^(nt)
    return principal * Math.pow(1 + rate / timesCompounded, timesCompounded * years);
}
 
// Why we use binary search instead of hash lookup:
// The dataset is already sorted from the upstream service, and we need
// range queries that hash maps can't efficiently support. Binary search
// gives us O(log n) lookups with O(1) range scan initiation.
const index = binarySearch(sortedUsers, targetId);
 
// WARNING: This method has O(n²) complexity. For collections over 1000 items,
// use bulkProcess() instead which batches into O(n log n) operations.
function processItems(items: Item[]): void {
    // ...
}
 
// TODO(ticket-1234): Replace with proper retry mechanism once circuit breaker is implemented
await sleep(1000);
await retryOperation();

Comments Signal Code Smell

If you find yourself writing a comment to explain what code does, consider whether better naming or function extraction would eliminate the need. Comments explaining what often indicate the code isn't self-explanatory. Comments explaining why are usually valuable.

Error Handling Layout

Error handling code can dominate a function's layout if not organized carefully. The goal is to keep the happy path prominent while handling errors cleanly.

Error Handling Layout Patterns
TypeScript
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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
// ❌ Error handling obscures happy path
async function fetchUserData(userId: string): Promise<UserData> {
    try {
        const user = await this.userRepo.findById(userId);
        if (!user) {
            throw new NotFoundError('User not found');
        }
        try {
            const preferences = await this.prefsRepo.findByUserId(userId);
            if (!preferences) {
                throw new NotFoundError('Preferences not found');
            }
            try {
                const activity = await this.activityRepo.findRecent(userId);
                return {
                    user,
                    preferences,
                    activity: activity || [],
                };
            } catch (activityError) {
                this.logger.warn('Failed to fetch activity', activityError);
                return { user, preferences, activity: [] };
            }
        } catch (prefError) {
            this.logger.warn('Failed to fetch preferences', prefError);
            return { user, preferences: DEFAULT_PREFERENCES, activity: [] };
        }
    } catch (userError) {
        this.logger.error('Failed to fetch user', userError);
        throw userError;
    }
}
 
// ✅ Guard clauses + flat structure + focused error handling
async function fetchUserData(userId: string): Promise<UserData> {
    // Fetch required data (throws if user not found)
    const user = await this.fetchUserOrThrow(userId);
    
    // Fetch optional data with fallbacks
    const preferences = await this.fetchPreferencesWithFallback(userId);
    const activity = await this.fetchActivityWithFallback(userId);
 
    return { user, preferences, activity };
}
 
private async fetchUserOrThrow(userId: string): Promise<User> {
    const user = await this.userRepo.findById(userId);
    if (!user) {
        throw new NotFoundError(`User ${userId} not found`);
    }
    return user;
}
 
private async fetchPreferencesWithFallback(userId: string): Promise<Preferences> {
    try {
        const prefs = await this.prefsRepo.findByUserId(userId);
        return prefs ?? DEFAULT_PREFERENCES;
    } catch (error) {
        this.logger.warn(`Failed to fetch preferences for ${userId}`, error);
        return DEFAULT_PREFERENCES;
    }
}
 
private async fetchActivityWithFallback(userId: string): Promise<Activity[]> {
    try {
        return await this.activityRepo.findRecent(userId) ?? [];
    } catch (error) {
        this.logger.warn(`Failed to fetch activity for ${userId}`, error);
        return [];
    }
}

Error Handling Layout Principles

•Extract error handling to separate functions — Complex try-catch blocks become simple function calls with error handling encapsulated.
•Use guard clauses for validation errors — Return or throw early for invalid inputs rather than nesting in try-catch.
•Keep try blocks small — Only wrap the code that can throw the exception you're catching.
•Separate required vs. optional operations — Required failures should throw; optional failures should log and continue with defaults.
•Don't use exceptions for control flow — Exceptions should be exceptional. Use return values for expected outcomes.

Automated Formatting and Enforcement

Manual formatting is error-prone and contentious. Modern development relies on automated tools to eliminate formatting debates and ensure consistency.

Essential Formatting Tools by Language
Language	Formatter	Linter	Key Configs
TypeScript/JS	Prettier	ESLint	`.prettierrc`, `.eslintrc`
Python	Black, autopep8	Pylint, Flake8, Ruff	`pyproject.toml`
Java	google-java-format	Checkstyle, SpotBugs	`checkstyle.xml`
Go	gofmt (built-in)	golint, staticcheck	N/A (standard format)
Rust	rustfmt (built-in)	Clippy	`rustfmt.toml`
C#	dotnet format	StyleCop, Roslyn analyzers	`.editorconfig`

Sample Prettier Configuration
1
2
3
4
5
6
7
8
9
10
11
12
// .prettierrc
{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 4,
  "useTabs": false,
  "trailingComma": "es5",
  "printWidth": 100,
  "bracketSpacing": true,
  "arrowParens": "avoid",
  "endOfLine": "lf"
}

Formatting Workflow Best Practices

•Format on save — Configure your IDE to auto-format on every save. This ensures you never commit unformatted code.
•Pre-commit hooks — Use Husky + lint-staged (JS) or pre-commit (Python) to run formatters before every commit.
•CI enforcement — Add a CI step that fails if code isn't formatted. prettier --check exits non-zero for unformatted code.
•Shared configuration — Commit formatter configs to the repo. All developers use the same rules.
•Adopt formatter defaults — Resist the urge to customize heavily. Default configs are battle-tested and reduce friction.

Let the Tools Decide

Formatting debates (tabs vs. spaces, 2 vs. 4 indent, etc.) waste energy. Pick a tool (Prettier, Black, gofmt), adopt its defaults, and move on. The best formatting style is the one the team stops thinking about because tools handle it automatically.

Summary: Code Layout Mastery

We've comprehensively covered code layout. Let's consolidate the key principles:

Key Takeaways

•Layout serves scanning — Code is read in scanning mode. Good layout makes scanning effective by providing predictable structure and visual landmarks.
•Order members consistently — Pick a convention (visibility-first or type-first) and apply it everywhere. Linters can enforce this.
•Use blank lines as paragraph breaks — Separate logical sections. One blank line between methods; blank lines between phases within methods.
•Respect line length limits — 80-120 characters. Break long lines intentionally at logical points.
•Files follow a standard structure — Imports → Types → Constants → Main exports → Helpers. Predictable structure aids navigation.
•Automate formatting — Use tools like Prettier, Black, gofmt. Format on save, enforce in CI. Never debate formatting manually.

Code layout checklist:

Class members ordered by consistent convention
Blank lines separate logical sections
Line length within limits (80-120 chars)
Imports organized by group and alphabetized
Functions structured: guards → logic → side effects → return
Comments explain why, not what
Error handling doesn't obscure happy path
Automated formatter configured and running

Module Complete:

With this page, we've completed Module 8: Code Organization & Structure. You now have a comprehensive understanding of:

Project structure — Layered, feature-based, and hybrid patterns
Package organization — Cohesion, coupling, and dependency management
Naming conventions — Variables, functions, classes, and domain-driven naming
Code layout — Ordering, spacing, formatting, and automation

Module Complete

Congratulations! You've mastered Code Organization & Structure. These skills apply to every project you work on—they're the foundation of professional code that teams can maintain and evolve. Well-organized code isn't just aesthetically pleasing; it's a competitive advantage that compounds over the life of every project.

4 / 4

Loading learning content...

System Design (LLD)Code Organization & Structure

Code Organization & Structure

LevelIntermediate

Duration75 mins

TopicCode Organization & Structure

4 / 4

Code Layout Best Practices

The Visual Dimension of Code

Code layout encompasses decisions like:

How do we order members within a class?
When should we use blank lines?
How do we format complex expressions?
What should appear at the top of a file vs. the bottom?
How do we group related functionality?

What You Will Learn

Why Layout Matters

How Layout Affects Development

•Scanning speed — Consistent ordering means developers know where to look. Public methods at the top? Always. Private helpers at the bottom? Guaranteed. This predictability accelerates navigation.
•Pattern recognition — Visual similarity signals logical similarity. When related methods are grouped and formatted consistently, the eye can quickly identify patterns.
•Error detection — Formatting inconsistencies often signal logic errors. A misaligned brace or an extra/missing blank line can indicate something went wrong during editing.
•Merge conflict prevention — Consistent formatting reduces spurious diff noise. When everyone formats the same way, diffs show only meaningful changes.
•Cognitive load reduction — When layout is predictable, the brain doesn't spend energy parsing structure. That energy goes to understanding logic.

❌ Inconsistent, hard-to-scan layout:

class OrderService {
private repo: OrderRepository;
public async getOrder(id: string) {
const order = await this.repo.find(id);
if (!order) { throw new NotFoundError(); }
return order;
}
constructor(repo: OrderRepository) {
this.repo = repo;
}
public async createOrder(data: CreateOrderData) {
const order = new Order(data);
await this.repo.save(order);
return order;
}
private validate(data: any): boolean {
return data.items?.length > 0;
}
}

No visual structure. Constructor in the middle. Private/public mixed.

✅ Clean, scannable layout:

class OrderService {
    private repo: OrderRepository;

    constructor(repo: OrderRepository) {
        this.repo = repo;
    }

    // --- Public API ---
    
    public async getOrder(id: string) {
        const order = await this.repo.find(id);
        if (!order) {
            throw new NotFoundError();
        }
        return order;
    }

    public async createOrder(data: CreateOrderData) {
        const order = new Order(data);
        await this.repo.save(order);
        return order;
    }

    // --- Private Helpers ---
    
    private validate(data: any): boolean {
        return data.items?.length > 0;
    }
}

Clear sections. Predictable ordering. Easy to scan.

The Newspaper Metaphor

Class Member Ordering

How you order members within a class significantly impacts readability. There are two dominant philosophies, each with merits:

Class Member Ordering Approaches
Approach	Order	Rationale
Visibility-first	Public → Protected → Private (within each: static → instance → constructor → methods → fields)	Most important (public API) visible first; implementation details hidden below
Member-type-first	Fields → Constructor → Methods (within each: static → instance → public → private)	Logical flow: initialization before behavior; state before operations

Recommended Class 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
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
/**
 * OrderService - Handles order lifecycle operations
 * 
 * Standard class structure: visibility-first ordering
 */
class OrderService {
    // ==========================================
    // 1. STATIC MEMBERS (if any)
    // ==========================================
    private static readonly DEFAULT_PAGE_SIZE = 20;
 
    // ==========================================
    // 2. INSTANCE FIELDS
    // ==========================================
    private readonly repository: OrderRepository;
    private readonly eventBus: EventBus;
    private readonly logger: Logger;
 
    // ==========================================
    // 3. CONSTRUCTOR
    // ==========================================
    constructor(
        repository: OrderRepository,
        eventBus: EventBus,
        logger: Logger
    ) {
        this.repository = repository;
        this.eventBus = eventBus;
        this.logger = logger;
    }
 
    // ==========================================
    // 4. PUBLIC METHODS (the class's API)
    // ==========================================
    
    /**
     * Retrieves an order by ID
     * @throws NotFoundError if order doesn't exist
     */
    public async getOrder(orderId: string): Promise<Order> {
        this.logger.debug(`Fetching order ${orderId}`);
        
        const order = await this.repository.findById(orderId);
        if (!order) {
            throw new NotFoundError(`Order ${orderId} not found`);
        }
        
        return order;
    }
 
    /**
     * Creates a new order from the given data
     */
    public async createOrder(data: CreateOrderData): Promise<Order> {
        this.validateOrderData(data);
        
        const order = this.buildOrder(data);
        await this.repository.save(order);
        
        await this.eventBus.publish(new OrderCreatedEvent(order));
        
        return order;
    }
 
    /**
     * Lists orders with pagination
     */
    public async listOrders(options: ListOptions = {}): Promise<PaginatedResult<Order>> {
        const pageSize = options.pageSize ?? OrderService.DEFAULT_PAGE_SIZE;
        return this.repository.findAll({ ...options, pageSize });
    }
 
    // ==========================================
    // 5. PRIVATE METHODS (implementation details)
    // ==========================================
    
    private validateOrderData(data: CreateOrderData): void {
        if (!data.items || data.items.length === 0) {
            throw new ValidationError('Order must have at least one item');
        }
        
        if (!data.customerId) {
            throw new ValidationError('Customer ID is required');
        }
    }
 
    private buildOrder(data: CreateOrderData): Order {
        return new Order({
            id: generateId(),
            customerId: data.customerId,
            items: data.items,
            status: OrderStatus.PENDING,
            createdAt: new Date(),
        });
    }
}

Consistency Over Preference

Vertical Spacing and Logical Grouping

Vertical Spacing Guidelines

•One blank line between methods — Separates distinct units of behavior. This is non-negotiable.
•One blank line between logical sections within a method — Separate setup from logic from cleanup.
•Two blank lines between major sections — Between class declarations, between imports and class, between groups of related methods.
•No blank lines within tightly coupled code — Lines that work together to achieve one small goal should stay together.
•Blank line after control structure blocks — After if/for/while blocks, a blank line separates the next thought.

Effective Vertical Spacing
TypeScript
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
// ❌ No vertical spacing - hard to read
async function processOrder(orderId: string): Promise<void> {
    const order = await this.orderRepo.findById(orderId);
    if (!order) {
        throw new NotFoundError('Order not found');
    }
    const customer = await this.customerRepo.findById(order.customerId);
    if (!customer) {
        throw new NotFoundError('Customer not found');
    }
    const paymentResult = await this.paymentService.charge(customer, order.total);
    if (!paymentResult.success) {
        await this.orderRepo.updateStatus(orderId, 'PAYMENT_FAILED');
        throw new PaymentError(paymentResult.message);
    }
    await this.orderRepo.updateStatus(orderId, 'PAID');
    await this.notificationService.sendConfirmation(customer.email, order);
    await this.inventoryService.reserve(order.items);
}
 
// ✅ Logical grouping with blank lines
async function processOrder(orderId: string): Promise<void> {
    // Fetch required entities
    const order = await this.orderRepo.findById(orderId);
    if (!order) {
        throw new NotFoundError('Order not found');
    }
    
    const customer = await this.customerRepo.findById(order.customerId);
    if (!customer) {
        throw new NotFoundError('Customer not found');
    }
 
    // Process payment
    const paymentResult = await this.paymentService.charge(customer, order.total);
    if (!paymentResult.success) {
        await this.orderRepo.updateStatus(orderId, 'PAYMENT_FAILED');
        throw new PaymentError(paymentResult.message);
    }
 
    // Update state and notify
    await this.orderRepo.updateStatus(orderId, 'PAID');
    await this.notificationService.sendConfirmation(customer.email, order);
    await this.inventoryService.reserve(order.items);
}

The paragraph principle:

Signs you need a blank line:

You're moving from setup to actual work
You're changing what entity you're operating on
A comment would be appropriate (instead of comment, use blank line + code paragraph)
You've finished one complete mini-task within a larger function

Avoid Excessive Blank Lines

Horizontal Formatting

Horizontal layout involves indentation, line length, alignment, and spacing within lines. These choices affect how easily the eye can follow code structure.

Horizontal Formatting Guidelines
Aspect	Guideline	Rationale
Line length	80-120 characters max	Prevents horizontal scrolling; multiple files side-by-side
Indentation	2 or 4 spaces (consistent)	Shows nesting hierarchy; tabs vs spaces - pick one
Operator spacing	Space around binary operators	`a + b` not `a+b`; improves readability
Comma spacing	Space after commas	`fn(a, b, c)` not `fn(a,b,c)`
Alignment	Avoid excessive alignment	Aligned code requires maintenance; changes cascade

Horizontal Formatting Examples
TypeScript
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
// ❌ Line too long - requires horizontal scrolling
const result = await this.orderService.createOrder({ customerId: customer.id, items: cart.items, shippingAddress: customer.defaultAddress, billingAddress: customer.billingAddress, paymentMethod: customer.preferredPayment });
 
// ✅ Broken across lines for readability
const result = await this.orderService.createOrder({
    customerId: customer.id,
    items: cart.items,
    shippingAddress: customer.defaultAddress,
    billingAddress: customer.billingAddress,
    paymentMethod: customer.preferredPayment,
});
 
// ❌ Over-aligned - hard to maintain
const name        = 'John';
const email       = 'john@example.com';
const phoneNumber = '555-1234';
const address     = '123 Main St';
 
// ✅ Simple, consistent formatting
const name = 'John';
const email = 'john@example.com';
const phoneNumber = '555-1234';
const address = '123 Main St';
 
// ❌ Cramped expressions
const total=price*quantity+tax-discount;
if(order.status==='pending'&&order.items.length>0){
 
// ✅ Spaced for clarity
const total = price * quantity + tax - discount;
if (order.status === 'pending' && order.items.length > 0) {
 
// Long conditions - break for readability
// ❌ Hard to parse
if (user.isActive && user.hasPermission('admin') && user.department === 'engineering' && !user.isOnLeave) {
 
// ✅ Each condition on its own line
if (
    user.isActive &&
    user.hasPermission('admin') &&
    user.department === 'engineering' &&
    !user.isOnLeave
) {
    // ...
}

Use Formatters Religiously

File Organization

A well-organized file follows a predictable structure from top to bottom. Readers should be able to navigate based on expectations about where things are.

Standard File Organization (TypeScript)
TypeScript
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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
// =====================================================
// 1. FILE HEADER (optional - auto-generated license, etc.)
// =====================================================
/**
 * OrderService.ts
 * 
 * Handles order lifecycle including creation, processing, and fulfillment.
 */
 
// =====================================================
// 2. IMPORTS - organized by category
// =====================================================
 
// External dependencies (node_modules)
import { Injectable } from '@nestjs/common';
import { v4 as uuid } from 'uuid';
 
// Internal absolute imports (project modules)
import { Logger } from '@/infrastructure/logging';
import { EventBus } from '@/infrastructure/events';
 
// Relative imports (same module/feature)
import { Order, OrderStatus } from './Order';
import { OrderRepository } from './OrderRepository';
import { CreateOrderData, OrderDTO } from './order.types';
 
// =====================================================
// 3. TYPE DEFINITIONS (if local to this file)
// =====================================================
 
interface ProcessingResult {
    success: boolean;
    orderId: string;
    message?: string;
}
 
// =====================================================
// 4. CONSTANTS (file-level)
// =====================================================
 
const MAX_ITEMS_PER_ORDER = 100;
const DEFAULT_PROCESSING_TIMEOUT_MS = 30000;
 
// =====================================================
// 5. MAIN CLASS/FUNCTION EXPORTS
// =====================================================
 
@Injectable()
export class OrderService {
    // ... class implementation
}
 
// =====================================================
// 6. HELPER FUNCTIONS (if not in separate file)
// =====================================================
 
function validateItemCount(items: OrderItem[]): void {
    if (items.length > MAX_ITEMS_PER_ORDER) {
        throw new ValidationError(`Cannot exceed ${MAX_ITEMS_PER_ORDER} items`);
    }
}
 
// =====================================================
// 7. DEFAULT EXPORT (if applicable)
// =====================================================
 
export default OrderService;

Import Organization Guidelines

•Group imports by source — External packages → Internal absolute → Relative imports. Separate groups with blank lines.
•Alphabetize within groups — Makes finding specific imports easier; many formatters do this automatically.
•Avoid wildcard imports — import * as foo obscures what's actually used; makes tree-shaking less effective.
•Keep imports minimal — Only import what you use. Some linters (eslint-plugin-unused-imports) can auto-remove unused imports.
•Consider barrel imports carefully — import { A, B, C } from './index' can cause circular dependency issues and bundle bloat.

One Export Per File

Function and Method Layout

Within functions, layout affects how easily readers can follow the logic. The key principle: keep related code together, and separate distinct phases.

Function Layout Patterns
TypeScript
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
46
47
// Well-structured function layout
async function processOrderSubmission(
    orderId: string,
    paymentDetails: PaymentDetails
): Promise<OrderConfirmation> {
    // Phase 1: Validation and early returns (guard clauses)
    const order = await this.orderRepo.findById(orderId);
    if (!order) {
        throw new NotFoundError(`Order ${orderId} not found`);
    }
    
    if (order.status !== OrderStatus.PENDING) {
        throw new InvalidStateError(`Cannot process order in ${order.status} state`);
    }
 
    // Phase 2: Gather required data
    const customer = await this.customerRepo.findById(order.customerId);
    const inventory = await this.inventoryService.checkAvailability(order.items);
    
    if (!inventory.allAvailable) {
        throw new InsufficientInventoryError(inventory.unavailableItems);
    }
 
    // Phase 3: Core business logic
    const paymentResult = await this.paymentService.processPayment({
        customerId: customer.id,
        amount: order.total,
        ...paymentDetails,
    });
 
    if (!paymentResult.success) {
        await this.handlePaymentFailure(order, paymentResult);
        throw new PaymentFailedError(paymentResult.errorMessage);
    }
 
    // Phase 4: Update state
    order.markAsPaid(paymentResult.transactionId);
    await this.orderRepo.save(order);
    
    // Phase 5: Side effects (notifications, events)
    await this.inventoryService.reserveItems(order.items);
    await this.eventBus.publish(new OrderPaidEvent(order));
    await this.notificationService.sendConfirmation(customer.email, order);
 
    // Phase 6: Return result
    return this.buildOrderConfirmation(order, paymentResult);
}

Function Layout Principles

•Guard clauses first — Handle invalid inputs and edge cases at the top. Return early. This keeps the 'happy path' at the lowest indentation level.
•Declare variables close to use — Don't declare all variables at the top of the function (old C style). Declare when first needed.
•Group related operations — Lines that work together should be adjacent. Separate groups with blank lines.
•Single level of abstraction — A function's statements should be at the same abstraction level. Don't mix high-level orchestration with low-level details.
•The step-down rule — Functions called by a function should appear below it. Reading top-to-bottom follows the call hierarchy.

Extract Phases to Functions

Comments and Documentation Layout

Comments are part of code layout. When and how to use them significantly affects readability. The goal: comments should add value, not restate the obvious.

When to Use Comments
Comment Type	Purpose	Example
JSDoc/Javadoc	Public API documentation	Parameters, return values, exceptions
Why comments	Explain non-obvious decisions	Why this algorithm, not another
Warning comments	Alert to potential issues	Performance implications, side effects
TODO/FIXME	Track technical debt	Known issues, planned improvements
Section markers	Delineate major sections	// --- Public API ---

Effective vs Ineffective Comments
TypeScript
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
46
47
48
49
50
51
52
53
54
// ❌ USELESS COMMENTS - Restate the obvious
// Increment counter
counter++;
 
// Check if user is active
if (user.isActive) { }
 
// Loop through items
for (const item of items) { }
 
// Constructor
constructor() { }
 
 
// ✅ VALUABLE COMMENTS - Add information not in the code
 
/**
 * Calculates compound interest using the standard formula.
 * 
 * @param principal - Initial investment amount
 * @param rate - Annual interest rate as decimal (e.g., 0.05 for 5%)
 * @param timesCompounded - Number of times interest compounds per year
 * @param years - Investment duration in years
 * @returns The final amount including principal and interest
 * 
 * @example
 * // $1000 at 5% compounded monthly for 10 years
 * calculateCompoundInterest(1000, 0.05, 12, 10) // Returns $1647.01
 */
function calculateCompoundInterest(
    principal: number,
    rate: number, 
    timesCompounded: number,
    years: number
): number {
    // Standard compound interest formula: A = P(1 + r/n)^(nt)
    return principal * Math.pow(1 + rate / timesCompounded, timesCompounded * years);
}
 
// Why we use binary search instead of hash lookup:
// The dataset is already sorted from the upstream service, and we need
// range queries that hash maps can't efficiently support. Binary search
// gives us O(log n) lookups with O(1) range scan initiation.
const index = binarySearch(sortedUsers, targetId);
 
// WARNING: This method has O(n²) complexity. For collections over 1000 items,
// use bulkProcess() instead which batches into O(n log n) operations.
function processItems(items: Item[]): void {
    // ...
}
 
// TODO(ticket-1234): Replace with proper retry mechanism once circuit breaker is implemented
await sleep(1000);
await retryOperation();

Comments Signal Code Smell

Error Handling Layout

Error handling code can dominate a function's layout if not organized carefully. The goal is to keep the happy path prominent while handling errors cleanly.

Error Handling Layout Patterns
TypeScript
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
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
// ❌ Error handling obscures happy path
async function fetchUserData(userId: string): Promise<UserData> {
    try {
        const user = await this.userRepo.findById(userId);
        if (!user) {
            throw new NotFoundError('User not found');
        }
        try {
            const preferences = await this.prefsRepo.findByUserId(userId);
            if (!preferences) {
                throw new NotFoundError('Preferences not found');
            }
            try {
                const activity = await this.activityRepo.findRecent(userId);
                return {
                    user,
                    preferences,
                    activity: activity || [],
                };
            } catch (activityError) {
                this.logger.warn('Failed to fetch activity', activityError);
                return { user, preferences, activity: [] };
            }
        } catch (prefError) {
            this.logger.warn('Failed to fetch preferences', prefError);
            return { user, preferences: DEFAULT_PREFERENCES, activity: [] };
        }
    } catch (userError) {
        this.logger.error('Failed to fetch user', userError);
        throw userError;
    }
}
 
// ✅ Guard clauses + flat structure + focused error handling
async function fetchUserData(userId: string): Promise<UserData> {
    // Fetch required data (throws if user not found)
    const user = await this.fetchUserOrThrow(userId);
    
    // Fetch optional data with fallbacks
    const preferences = await this.fetchPreferencesWithFallback(userId);
    const activity = await this.fetchActivityWithFallback(userId);
 
    return { user, preferences, activity };
}
 
private async fetchUserOrThrow(userId: string): Promise<User> {
    const user = await this.userRepo.findById(userId);
    if (!user) {
        throw new NotFoundError(`User ${userId} not found`);
    }
    return user;
}
 
private async fetchPreferencesWithFallback(userId: string): Promise<Preferences> {
    try {
        const prefs = await this.prefsRepo.findByUserId(userId);
        return prefs ?? DEFAULT_PREFERENCES;
    } catch (error) {
        this.logger.warn(`Failed to fetch preferences for ${userId}`, error);
        return DEFAULT_PREFERENCES;
    }
}
 
private async fetchActivityWithFallback(userId: string): Promise<Activity[]> {
    try {
        return await this.activityRepo.findRecent(userId) ?? [];
    } catch (error) {
        this.logger.warn(`Failed to fetch activity for ${userId}`, error);
        return [];
    }
}

Error Handling Layout Principles

•Extract error handling to separate functions — Complex try-catch blocks become simple function calls with error handling encapsulated.
•Use guard clauses for validation errors — Return or throw early for invalid inputs rather than nesting in try-catch.
•Keep try blocks small — Only wrap the code that can throw the exception you're catching.
•Separate required vs. optional operations — Required failures should throw; optional failures should log and continue with defaults.
•Don't use exceptions for control flow — Exceptions should be exceptional. Use return values for expected outcomes.

Automated Formatting and Enforcement

Manual formatting is error-prone and contentious. Modern development relies on automated tools to eliminate formatting debates and ensure consistency.

Essential Formatting Tools by Language
Language	Formatter	Linter	Key Configs
TypeScript/JS	Prettier	ESLint	`.prettierrc`, `.eslintrc`
Python	Black, autopep8	Pylint, Flake8, Ruff	`pyproject.toml`
Java	google-java-format	Checkstyle, SpotBugs	`checkstyle.xml`
Go	gofmt (built-in)	golint, staticcheck	N/A (standard format)
Rust	rustfmt (built-in)	Clippy	`rustfmt.toml`
C#	dotnet format	StyleCop, Roslyn analyzers	`.editorconfig`

Sample Prettier Configuration
1
2
3
4
5
6
7
8
9
10
11
12
// .prettierrc
{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 4,
  "useTabs": false,
  "trailingComma": "es5",
  "printWidth": 100,
  "bracketSpacing": true,
  "arrowParens": "avoid",
  "endOfLine": "lf"
}

Formatting Workflow Best Practices

•Format on save — Configure your IDE to auto-format on every save. This ensures you never commit unformatted code.
•Pre-commit hooks — Use Husky + lint-staged (JS) or pre-commit (Python) to run formatters before every commit.
•CI enforcement — Add a CI step that fails if code isn't formatted. prettier --check exits non-zero for unformatted code.
•Shared configuration — Commit formatter configs to the repo. All developers use the same rules.
•Adopt formatter defaults — Resist the urge to customize heavily. Default configs are battle-tested and reduce friction.

Let the Tools Decide

Summary: Code Layout Mastery

We've comprehensively covered code layout. Let's consolidate the key principles:

Key Takeaways

•Layout serves scanning — Code is read in scanning mode. Good layout makes scanning effective by providing predictable structure and visual landmarks.
•Order members consistently — Pick a convention (visibility-first or type-first) and apply it everywhere. Linters can enforce this.
•Use blank lines as paragraph breaks — Separate logical sections. One blank line between methods; blank lines between phases within methods.
•Respect line length limits — 80-120 characters. Break long lines intentionally at logical points.
•Files follow a standard structure — Imports → Types → Constants → Main exports → Helpers. Predictable structure aids navigation.
•Automate formatting — Use tools like Prettier, Black, gofmt. Format on save, enforce in CI. Never debate formatting manually.

Code layout checklist:

Class members ordered by consistent convention
Blank lines separate logical sections
Line length within limits (80-120 chars)
Imports organized by group and alphabetized
Functions structured: guards → logic → side effects → return
Comments explain why, not what
Error handling doesn't obscure happy path
Automated formatter configured and running

Module Complete:

With this page, we've completed Module 8: Code Organization & Structure. You now have a comprehensive understanding of:

Project structure — Layered, feature-based, and hybrid patterns
Package organization — Cohesion, coupling, and dependency management
Naming conventions — Variables, functions, classes, and domain-driven naming
Code layout — Ordering, spacing, formatting, and automation

Module Complete

4 / 4