Formatting Shapes How Code Is Read
What this concept is
Formatting creates reading rhythm. It groups related ideas, separates unrelated ones, and lets the eye scan from high-level intention down into detail.
Why it matters here
Even good names can be hidden inside a wall of code. Formatting is what turns code from a dense dump into a readable sequence of decisions.
Concrete example
This is harder to scan:
def checkout(cart,user,payment):
validate_cart(cart);validate_user(user);charge(payment);reserve_stock(cart);send_receipt(user)
This is easier:
def checkout(cart, user, payment):
validate_cart(cart)
validate_user(user)
charge(payment)
reserve_stock(cart)
send_receipt(user)
The second version visually shows phases of work.
Common confusion / misconception
Formatting is not only about line length or linter compliance. Those are useful constraints, but the deeper purpose is communication. The file should read top-down, with higher-level steps visible before lower-level details.
How to use it
Prefer:
- short files over sprawling ones when responsibilities split cleanly
- blank lines to separate conceptual sections
- nearby placement for related code
- consistent indentation and ordering
- stepdown structure, where helpers appear near what calls them when the language and project style allow it
Check yourself
What reading advantage does vertical separation provide that comments often try to imitate?
Mini drill or application
Take one dense function and reformat it without changing behavior. Your goal is to make the phases of work visible before changing any names or logic.