Code Craft

This section collects principles and techniques for writing code well, independent of any specific language, framework, or stack. The focus is the unit-of-work that engineers spend most of their time inside: a name, a function, a class, a module, a change.

The material distills ideas from the established literature on software construction — Code Complete, Refactoring, The Pragmatic Programmer, Clean Code — but is organized by concern, not by source. When two books disagree, both perspectives are noted; when they agree, the consensus is treated as default practice.

Topics

Fundamentals

• Naming — Choosing names that survive review, refactor, and time.
• Functions — Cohesion, parameters, return values, and the right level of abstraction.
• Classes — Class size, single responsibility, encapsulation, and composition.
• Variables — Scope, lifetime, mutability, and initialization.
• Comments — What deserves a comment, what does not, and what to write instead.
• Formatting — Vertical and horizontal layout, file organization.

Logic & Control

• Control Flow — Conditionals, loops, early returns, and table-driven alternatives.
• Error Handling — Defensive boundaries, assertions, exceptions, and recovery strategy.
• Concurrency — Principles for writing correct concurrent code.

Design

• Design Principles — SOLID, Law of Demeter, Tell-Don't-Ask, and structural rules.
• Design by Contract — Preconditions, postconditions, invariants, and stating what correct means.
• Boundaries — Working with third-party code and external services.
• API Design — Public interfaces that are minimal, stable, and easy to use correctly.
• Simplicity — The four rules of simple design and the cost of complexity.
• Duplication — DRY, orthogonality, and the kinds of duplication that matter.

Quality

• Testable Code — Writing code that is easy to test, and tests that are easy to maintain.
• Debugging — A systematic discipline for finding and fixing defects.
• Performance — When to optimize, how to measure, and which trade-offs are worth making.

Refactoring

• Refactoring — Recognizing code smells, applying mechanical refactorings, and choosing when to act.

Mindset

• Pragmatic Mindset — Habits and attitudes that make the daily practice of programming sustainable.

Scope and Boundaries

This section is deliberately narrow:

The goal is to make these decisions repeatable: not "what looks clean to me today," but a shared standard that holds up across reviewers and across time.

How to Use This Section

The section is structured to be read in order, but each page is self-contained. Common entry points:

• New to the team? Start with Naming, Functions, Variables, Comments — the four pages that have the most influence on day-to-day code.
• Reviewing code? Code Smells (under Refactoring) gives a vocabulary for review comments; Design Principles gives the structural framing.
• Designing something new? Classes, Design Principles, and Boundaries address the decisions made before code is written.
• Maintaining legacy code? Refactoring, Testable Code, and Debugging are the relevant disciplines.
• Hitting a recurring problem? Each page ends with a pre-commit checklist that captures its core in question form.