Code Should Be Easy to Understand
- What Makes Code "Better"
- The Fundamental Theorem of Readability
- Is Small Always Better
- Does Time-Till-Understanding Conflict with Other Goals? like efficient, well-architected, easy to test
- The hard part is it requires extra work to constantly think about whether an imaginary outsider would find your code easy to understand.
Surface-Level Improvements.
Packing information into your names.
- Choose specific, concrete names, not generic and abstract names.
- Attach important details
- Use longer names for larger scope
- Actively scrutinize your names by asking yourself "what other meanings could someone interpret from this name"
- Names That Can't Be Misconstrued
- Why Do Aesthetics Matter
- Pick a Meaningful Order, and Use it Consistently
- Organize declarations into Blocks
- Break Code into "Paragraphs"
Comment
- Knowing what to comment
- What not to comment
- Don't Comment Just for the Sake of Commenting
- Don't Comment Bad Names - Fix the Names instead
- Recording Your Thoughts
- Include Director Commentary
- Comment the Flaws in Your Code
- Comment on Your Constants
- Put Yourself in the Reader's Shoes
- "Big Picture" Comments
- Summary Comments
- Final Thoughts --- Getting Over Writer's Block
- Describe Function Behavior Precisely
- Use Input/Output Examples that illustrate Corner Cases
- State the intent of Your Code
- Use Information-Dense Words
Making Control Flow Easy to Follow
- The Order of Arguments in Conditionals
- The Order of if/else Blocks
- Returning Early from a Function
- Minimize Nesting
Breaking Down Giant Expressions
- Explaining Variables
- Summary Variables
- Using De Morgan's Laws
- macro functions
Variables and Readability
- Eliminating Variables
- Shrink the Scope of Your Variables
- Prefer Write-Once Variables
Reorganizing Your Code
Extracting Unrelated Subproblems.
- Pure Utility/ General-Purpose Code
- Project-Specific Functionality
- Simplifying an Existing Interface
- Reshaping an interface to Your Needs
One Task at a Time
- Brea down your giant expression into more digestible pieces
- Code should be organized so that it's doning only one task at a time
Turning Thoughts into Code
- Describing Logic Clearly
- Knowing Your Libraries Helps
Writing Less Code
- The most readable code is no code at all
- Don't Bother Implementing That Feature -- Your won't need it
- Question and Break Down Your Requirements
- Be Familiar with the Libraries Around You
Testing and Readability
- Test code should be readable so that other coders are comfortable changing or adding tests
- In general, you should pick the simplest set of inputs that completely exercise the code
- Prefer clean and simple test values that still get the job down.
- Creating the Minimal Test Statement
- Implementing Custom "Minilanguages"
- Choose Good Test Inputs
- Naming Tests Functions
- Multiple Tests of Functionality
Key Idea
General about What's good code
- Code should be easy to understand
- Code should be written to minimize the time it would take for someone else to understand it
- It's better to be clear and precise than to be cute
- Consistent Style is more important than the "right" style
- Instead of minimizing the number of lines, a better metric is to minimize the time needed for someone to understand it.
- Beaware of "clever" nuggets of code ---- they're often confusion when others read the code later
- Code should be organized so that it's doing only one task at a time
- The most readable code is no code at all
Specific about How to write good code
- Pack information into your name
- Actively scrutinize your names by asking yourself, "what other meaning could someone interpret from this name
- The purpose of commenting is to help the reader known as much as the writer did
- Don't comment on facts that can be derived quickly from the code itself
- Comments should have a high information-to-space ratio
- Make all your conditionals, loops, and other changes to control flow as "natural" as possible ---- written in a way that doesn't make the reader stop and reread your code!
- Breaking down your giant expression into more digestible pieces
- Make your variable visible by as few lines of code as possible
- The more places a variable is manipulated, the harder it is to reason about its current value
- Looking at your code from a fresh perspective when you're making changes. Step back and look at it as a whole
- Test should be readable so that other coders are comfortable changing or adding tests
- In general, you should pick the simplest set of inputs that completely exercise the code
- Prefer clean and simple test values that still get the job done