Best-Practices

The third factor of the 12-Factor App methodology states: “Store config in the environment.” Simple advice that’s surprisingly easy to get wrong. The Core Principle Configuration that varies between environments (dev, staging, production) should come from environment variables, not code. This includes: Database connection strings API keys and secrets Feature flags Service URLs Port numbers Log levels What stays in code: application logic, default behaviors, anything that doesn’t change between deploys. ...

Most production incidents I’ve debugged came down to configuration. A missing environment variable. A wrong database URL. A feature flag stuck in the wrong state. Code was fine; configuration was the problem. Configuration management is the unsexy work that prevents those 3 AM pages. The Core Principles 1. Separate Configuration from Code Configuration should never be baked into your application binary or container image. Wrong: 1 2 # Hardcoded in code DATABASE_URL = "postgres://prod:password@db.example.com/myapp" Also wrong: ...

Code review is a skill separate from coding. A great programmer can give terrible reviews — nitpicking style while missing logic bugs, or rubber-stamping everything to avoid conflict. Good reviews improve code quality and team knowledge. Bad reviews slow everything down. These practices help you do reviews that actually help. The Reviewer’s Mindset You’re Not the Gatekeeper ❌ ✅ " " I D o w e o s u l t d h n i ' s t w h o a r v k e c w o r r i r t e t c e t n l y i t a n t d h i m s a i w n a t y a " i n a b l y ? " Your job isn’t to make the code match your personal style. It’s to catch problems and improve clarity. ...

Everyone agrees testing is important. Few agree on how much, what kind, and where to focus. The testing pyramid provides a framework: many fast unit tests, fewer integration tests, even fewer end-to-end tests. But the pyramid only works if you understand why each layer exists. The Pyramid E I U 2 n n E t i e t T g e r T s a e t t s s i t o s ( n f ( e T m w e a , s n t y s s , l o ( f w s a , o s m t e e , x , p c e m h n e e s d a i i p v u ) e m ) s p e e d ) Unit tests: Test individual functions/classes in isolation Integration tests: Test components working together E2E tests: Test the full system like a user would ...

Errors are inevitable. Networks fail. Disks fill up. Services crash. Users input garbage. The question isn’t whether your system will encounter errors — it’s how it will behave when it does. Good error handling is the difference between “the system recovered automatically” and “we lost customer data.” Fail Fast, Fail Loud Detect problems early and report them clearly: 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 # ❌ Bad: Silent failure def process_order(order): try: result = payment_service.charge(order) except Exception: pass # Swallow error, pretend it worked return {"status": "ok"} # ✅ Good: Fail fast with clear error def process_order(order): if not order.items: raise ValidationError("Order must have at least one item") if order.total <= 0: raise ValidationError("Order total must be positive") result = payment_service.charge(order) # Let it fail if it fails return {"status": "ok", "charge_id": result.id} Silent failures are debugging nightmares. If something goes wrong, make it obvious. ...

The twelve-factor app methodology emerged from Heroku’s experience deploying thousands of applications. These principles create applications that work well in modern cloud environments — containerized, horizontally scalable, and continuously deployed. They’re not arbitrary rules. Each factor solves a real problem. I. Codebase One codebase tracked in version control, many deploys. ✅ m ├ ├ └ ❌ m m m y ─ ─ ─ y y y G a ─ ─ ─ B a a a o p a p p p o p . s d d p p p d g r e : - - - : i c p p s d t l r t e o o a v y d g e u i l t c n o o t g p : i m e s n n t / t a / g i n g , p r o d u c t i o n , f e a t u r e - b r a n c h e s Different environments come from the same codebase. Configuration, not code, varies between deploys. ...

You can write brilliant code that nobody can use because the documentation is impenetrable. Or you can write average code with excellent docs that becomes everyone’s go-to solution. Documentation is a multiplier. These principles help you write docs that work. Know Your Audience Different readers need different docs: Tutorials (learning-oriented): “Follow these steps to build X” For newcomers Hand-holding is okay Complete, working examples Progressive complexity How-to Guides (task-oriented): “How to do X” ...

Configuration management sounds simple until you’re debugging why production is reading from the staging database at 3am. Here’s how to structure configuration so environments stay isolated and secrets stay secret. The Twelve-Factor Baseline The Twelve-Factor App got it right: store config in environment variables. But that’s just the starting point. Real systems need layers. ┌ │ ├ │ ├ │ ├ │ └ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ R ─ S ─ E ─ D ─ ─ u ─ e ─ n ─ e ─ ─ n ─ c ─ v ─ f ─ ─ t ─ r ─ i ─ a ─ ─ i ─ e ─ r ─ u ─ ─ m ─ t ─ o ─ l ─ ─ e ─ s ─ n ─ t ─ ─ ─ ─ m ─ ─ ─ E ─ M ─ e ─ c ─ ─ n ─ a ─ n ─ o ─ ─ v ─ n ─ t ─ n ─ ─ i ─ a ─ - ─ f ─ ─ r ─ g ─ s ─ i ─ ─ o ─ e ─ p ─ g ─ ─ n ─ r ─ e ─ ─ ─ m ─ ─ c ─ i ─ ─ e ─ ( ─ i ─ n ─ ─ n ─ V ─ f ─ ─ ─ t ─ a ─ i ─ c ─ ─ ─ u ─ c ─ o ─ ─ V ─ l ─ ─ d ─ ─ a ─ t ─ c ─ e ─ ─ r ─ , ─ o ─ ─ ─ i ─ ─ n ─ ─ ─ a ─ A ─ f ─ ─ ─ b ─ W ─ i ─ ─ ─ l ─ S ─ g ─ ─ ─ e ─ ─ ─ ─ ─ s ─ S ─ f ─ ─ ─ ─ S ─ i ─ ─ ─ ─ M ─ l ─ ─ ─ ─ , ─ e ─ ─ ─ ─ ─ s ─ ─ ─ ─ e ─ ─ ─ ─ ─ t ─ ─ ─ ─ ─ c ─ ─ ─ ─ ─ . ─ ─ ─ ─ ─ ) ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ─ ┐ │ ┤ │ ┤ │ ┤ │ ┘ ← ← H L i o g w h e e s s t t p p r r i i o o r r i i t t y y Each layer overrides the one below it. Defaults live in code, environment-specific values in config files, secrets in a secrets manager, and runtime overrides in environment variables. ...

Your API will be called wrong. Clients will send garbage. Load will spike unexpectedly. Authentication will be misconfigured. The question isn’t whether these things happen — it’s whether your API degrades gracefully or explodes. Here’s how to build APIs that survive contact with the real world. Input Validation: Trust Nothing Every field, every header, every query parameter is hostile until proven otherwise. 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 from pydantic import BaseModel, Field, validator from typing import Optional import re class CreateUserRequest(BaseModel): email: str = Field(..., max_length=254) name: str = Field(..., min_length=1, max_length=100) age: Optional[int] = Field(None, ge=0, le=150) @validator('email') def validate_email(cls, v): # Don't just regex — actually validate structure if not re.match(r'^[^@]+@[^@]+\.[^@]+$', v): raise ValueError('Invalid email format') return v.lower().strip() @validator('name') def sanitize_name(cls, v): # Remove control characters, normalize whitespace v = re.sub(r'[\x00-\x1f\x7f-\x9f]', '', v) return ' '.join(v.split()) Key principles: ...

Learn how to design idempotent APIs that handle duplicate requests safely, making your systems more resilient to network failures and client retries.