Code Structure, Comments & Formatting
Core Principle: Good code is readable without needing comments. While comments can sometimes clarify complex logic, they often reduce readability, add redundancy, or even mislead.
The Reality About Comments
The common belief: Comments help with code readability.
The reality: Comments often have the opposite effect. Proper code formatting proves far more effective:
✅ Keep lines short and readable
✅ Add strategic blank lines between concepts
✅ Use descriptive names that explain intent
✅ Structure code logically
Bottom line: If your code needs comments to be understood, it probably needs better structure and naming instead.
❌ Bad Comments to Avoid
🚫 Dividers & Markers
❌ Why avoid:
Redundant—clean code with proper naming makes sections obvious
Interrupts reading flow
Adds visual clutter
Makes code analysis harder
✅ Better approach: Use proper file organization and naming conventions.
🚫 Redundant Information
❌ Why avoid:
Adds nothing new—the function name already explains its purpose
Wastes reading time
Clutters the codebase
Poor alternative:
✅ Better approach: Fix the naming, not add comments!
🚫 Commented-Out Code
❌ Why avoid:
Clutters your code files
Makes navigation difficult
Creates uncertainty—why is it commented out?
✅ Better approach: Delete it! Use version control (Git) to retrieve old code if needed.
Pro tip: Trust your version control system. If you need the code later, you can always get it from the repository history.
🚫 Misleading Comments
❌ Why avoid:
This is the worst kind of comment!
Creates confusion and contradicts the code
Forces developers to analyze the entire implementation
Erodes trust in the codebase
Critical rule: Always ensure comments match what the code actually does—or better yet, make the code self-explanatory.
✅ When Comments Are Actually Good
While comments don't improve your code directly, there are a few legitimate use cases:
⚖️ Legal Information
When appropriate:
Required by company policy or legal requirements
Usually placed at the top of files
Minimal impact on readability
📖 Required Explanations
When appropriate:
Complex expressions (like regex) that aren't immediately readable
Algorithm explanations for non-obvious logic
Business rule documentation that can't be expressed in code
Key principle: Even with a descriptive name like passwordRegex, the specific validation rules aren't immediately clear. The comment adds genuine value here.
⚠️ Warnings
When appropriate:
Environmental requirements
Performance implications
Known limitations
Edge cases that aren't obvious
📝 Todo Notes
When appropriate:
Marking incomplete work temporarily
Tracking technical debt
Modern IDEs help find and manage TODOs
⚠️ Warning: Use sparingly! Too many TODOs indicate:
Incomplete implementations
Poor planning
Technical debt accumulation
Best practice: Finish features completely before committing, or use a task tracking system instead.
🧱 Vertical Formatting
Vertical formatting uses blank lines and logical grouping to guide the reader's eye through your code.
The Power of Blank Lines
❌ Without spacing (harder to read):
✅ With strategic spacing (much easier to read):
Result: Same logic, dramatically improved readability!
Vertical Density & Distance
Two complementary principles:
Vertical Density
Keep related concepts close together
Shows they work as a unit
Vertical Distance
Separate unrelated concepts with blank lines
Shows logical boundaries
Example in action:
Analysis:
✅ Validation and user creation are separate concepts → blank line between them
✅ Creating user and saving it are tightly related → no blank line between them
The Stepdown Rule
Principle: Functions that call other functions should appear above them (when your language allows).
✅ Good example:
Benefits:
Creates logical top-to-bottom reading flow
High-level overview first, details below
Easier to understand the code's structure
Natural navigation pattern
Splitting Code Across Files
When to split:
Files exceed 200-300 lines
Multiple class definitions in one file
Mixed concerns or responsibilities
Difficult to navigate or find specific code
How to split:
Benefits:
Each file has a single, clear purpose
Easier to find and modify code
Better team collaboration
Improved maintainability
↔️ Horizontal Formatting
Horizontal formatting focuses on keeping lines short, readable, and maintainable.
Breaking Long Lines
❌ Too long (hard to read):
✅ Better (readable and maintainable):
Why it's better:
Each line has a single, clear purpose
Easier to debug (can set breakpoints on specific lines)
Easier to read and understand logic flow
Simpler to modify individual steps
General guideline: Keep lines under 80-120 characters when possible.
Using Concise Names
Names should be descriptive but not wastefully verbose.
Key principle: Context provides meaning. Avoid unnecessary words—clarity doesn't mean verbosity.
📚 Quick Reference Guide
❌ Avoid These Comments
Dividers
// !!!!!!!
Redundant, clutters code
Redundant
function create() { // creates user }
Repeats obvious information
Commented code
// oldFunction() { ... }
Use version control instead
Misleading
function login() { // signup }
Contradicts actual behavior
✅ Acceptable Comments
Legal
// (c) Company 2024
Required by policy
Explanations
// regex validates email
Complex logic clarification
Warnings
// requires dev server
Important constraints
TODOs
// TODO: add validation
Temporary markers (sparingly)
📏 Formatting Checklist
Vertical Formatting:
Blank lines between unrelated concepts
Related code kept close together
Functions ordered by call hierarchy (stepdown rule)
Large files split into focused modules
Horizontal Formatting:
Lines under 80-120 characters
Long lines broken into multiple readable lines
Names are descriptive but concise
No unnecessary verbosity in naming
🎯 Final Thoughts
Remember: Clean code is self-documenting.
The best comment is the one you don't need to write because:
Your function names clearly state their purpose
Your variable names reveal their intent
Your code structure shows the logical flow
Your formatting guides the reader naturally
Invest in:
✅ Thoughtful naming
✅ Strategic formatting
✅ Logical structure
✅ Clear organization
Not in:
❌ Compensating with comments
❌ Explaining poor code
❌ Documenting the obvious
The ultimate goal: Write code that reads like well-written prose—clear, logical, and effortless to understand.
Happy coding! 🚀
"Code is read more often than it is written." — Guido van Rossum
Last updated