The Newspaper Metaphor
Think of a well-structured source file like a newspaper article. The top gives you the headline and key points — public API, exported functions. As you scroll down, detail increases — private helpers, implementation. A reader should understand the module's purpose from the first 20 lines, without digging into implementation.
Private detail at the top
function _validateEmailFormat(email):
return "@" in email
function _hashPassword(password):
return hash(password)
function registerUser(name, email, password): // ← hard to find
...Public API first
function registerUser(name, email, password):
if not _isValidEmail(email):
raise ValueError("Invalid email")
return {
name: name,
password: _hashPassword(password),
}
// ── Private helpers ──────────
function _isValidEmail(email): ...
function _hashPassword(password): ...Vertical Openness and Density
Blank lines are paragraph breaks for code. Use them to separate concepts — imports from class declaration, methods from each other. Don't add blank lines inside logic that belongs together — dense code signals tight coupling.
No breathing room
import FileSystem
import Platform
class UserService:
db=null
function find(id):
return db.query(id)
function save(user):
db.insert(user)Blank lines separate concepts
import FileSystem
import Platform
class UserService:
db = null
function find(userId):
return db.query(userId)
function save(user):
db.insert(user)Horizontal Formatting
Keep lines under 120 characters — long lines force horizontal scrolling and hide the structure. Indentation is the visual contract that tells readers which code belongs where. Never fight your team's agreed formatter (black, prettier, eslint). Personal style is irrelevant in a team setting.
160+ chars, horizontal scroll
function calculateOrderTotal(order, user, discountService, taxService, currencyConverter, targetCurrency):
return currencyConverter.convert(taxService.apply(discountService.apply(order.subtotal, user.tier), order.region), targetCurrency)Broken into readable steps
function calculateOrderTotal(
order, user,
discountService, taxService,
currencyConverter,
targetCurrency,
):
subtotal = discountService.apply(
order.subtotal, user.tier)
withTax = taxService.apply(
subtotal, order.region)
return currencyConverter.convert(
withTax, targetCurrency)Code Challenge
Format This Mess — apply the newspaper metaphor, add blank lines, break the long line.
Key takeaway
Formatting is not cosmetic — it's the visual language you use to communicate structure to the next developer.