book

The Art of Readable Code

by Dustin Boswell, Trevor Foucher

November 2011

Intermediate to advanced

206 pages

4h 32m

English

O'Reilly Media, Inc.

Read now

Unlock full access

What This Book Is AboutHow to Read This BookUsing Code ExamplesSafari® Books OnlineHow to Contact UsAcknowledgments
What Makes Code “Better”?The Fundamental Theorem of ReadabilityIs Smaller Always Better?Does Time-Till-Understanding Conflict with Other Goals?The Hard Part
Choose Specific WordsFinding More “Colorful” WordsAvoid Generic Names Like tmp and retvaltmpLoop IteratorsThe Verdict on Generic NamesPrefer Concrete Names over Abstract NamesExample: DISALLOW_EVIL_CONSTRUCTORSExample: --run_locallyAttaching Extra Information to a NameValues with UnitsEncoding Other Important AttributesHow Long Should a Name Be?Shorter Names Are Okay for Shorter ScopeTyping Long Names—Not a Problem AnymoreAcronyms and AbbreviationsThrowing Out Unneeded WordsUse Name Formatting to Convey MeaningOther Formatting ConventionsSummary
Example: Filter()Example: Clip(text, length)Prefer min and max for (Inclusive) LimitsPrefer first and last for Inclusive RangesPrefer begin and end for Inclusive/Exclusive RangesNaming BooleansMatching Expectations of UsersExample: get*()Example: list::size()Example: Evaluating Multiple Name CandidatesSummary
Why Do Aesthetics Matter?Rearrange Line Breaks to Be Consistent and CompactUse Methods to Clean Up IrregularityUse Column Alignment When HelpfulShould You Use Column Alignment?Pick a Meaningful Order, and Use It ConsistentlyOrganize Declarations into BlocksBreak Code into “Paragraphs”Personal Style versus ConsistencySummary
What NOT to CommentDon’t Comment Just for the Sake of CommentingDon’t Comment Bad Names—Fix the Names InsteadRecording Your ThoughtsInclude “Director Commentary”Comment the Flaws in Your CodeComment on Your ConstantsPut Yourself in the Reader’s ShoesAnticipating Likely QuestionsAdvertising Likely Pitfalls“Big Picture” CommentsSummary CommentsFinal Thoughts—Getting Over Writer’s BlockSummary
Keep Comments CompactAvoid Ambiguous PronounsPolish Sloppy SentencesDescribe Function Behavior PreciselyUse Input/Output Examples That Illustrate Corner CasesState the Intent of Your Code“Named Function Parameter” CommentsUse Information-Dense WordsSummary

The Order of Arguments in ConditionalsThe Order of if/else BlocksThe ?: Conditional Expression (a.k.a. “Ternary Operator”)Avoid do/while LoopsReturning Early from a FunctionThe Infamous gotoMinimize NestingHow Nesting AccumulatesRemoving Nesting by Returning EarlyRemoving Nesting Inside LoopsCan You Follow the Flow of Execution?Summary
Explaining VariablesSummary VariablesUsing De Morgan’s LawsAbusing Short-Circuit LogicExample: Wrestling with Complicated LogicFinding a More Elegant ApproachBreaking Down Giant StatementsAnother Creative Way to Simplify ExpressionsSummary
Eliminating VariablesUseless Temporary VariablesEliminating Intermediate ResultsEliminating Control Flow VariablesShrink the Scope of Your Variablesif Statement Scope in C++Creating “Private” Variables in JavaScriptJavaScript Global ScopeNo Nested Scope in Python and JavaScriptMoving Definitions DownPrefer Write-Once VariablesA Final ExampleSummary
Introductory Example: findClosestLocation()Pure Utility CodeOther General-Purpose CodeUnexpected BenefitsCreate a Lot of General-Purpose CodeProject-Specific FunctionalitySimplifying an Existing InterfaceReshaping an Interface to Your NeedsTaking Things Too FarSummary
Tasks Can Be SmallExtracting Values from an ObjectApplying “One Task at a Time”Another ApproachA Larger ExampleFurther ImprovementsSummary
Describing Logic ClearlyKnowing Your Libraries HelpsApplying This Method to Larger ProblemsAn English Description of the SolutionApplying the Method RecursivelySummary
Don’t Bother Implementing That Feature—You Won’t Need ItQuestion and Break Down Your RequirementsExample: A Store LocatorExample: Adding a CacheKeeping Your Codebase SmallBe Familiar with the Libraries Around YouExample: Lists and Sets in PythonWhy Reusing Libraries Is Such a WinExample: Using Unix Tools Instead of CodingSummary
Make Tests Easy to Read and MaintainWhat’s Wrong with This Test?Making This Test More ReadableCreating the Minimal Test StatementImplementing Custom “Minilanguages”Making Error Messages ReadableUsing Better Versions of assert()Hand-Crafted Error MessagesChoosing Good Test InputsSimplifying the Input ValuesMultiple Tests of FunctionalityNaming Test FunctionsWhat Was Wrong with That Test?Test-Friendly DevelopmentGoing Too FarSummary
The ProblemDefining the Class InterfaceImproving the NamesImproving the CommentsAttempt 1: A Naive SolutionIs the Code Easy to Understand?An Easier-to-Read VersionPerformance ProblemsAttempt 2: Conveyor Belt DesignImplementing the Two-Stage Conveyor Belt DesignAre We Done?Attempt 3: A Time-Bucketed DesignImplementing the Time-Bucketed DesignImplementing TrailingBucketCounterImplementing ConveyorQueueComparing the Three SolutionsSummary
Books on Writing High-Quality CodeBooks on Various Programming TopicsBooks of Historical Note

Content preview from The Art of Readable Code

A Note Regarding Supplemental Files

Supplemental files and examples for this book can be found at http://examples.oreilly.com/9780596802301/. Please use a standard desktop web browser to access these files, as they may not be accessible from all ereader devices.

All code files or examples referenced in the book will be available online. For physical books that ship with an accompanying disc, whenever possible, we’ve posted all CD/DVD content. Note that while we provide as much of the media content as we are able via free download, we are sometimes limited by licensing restrictions. Please direct any questions or concerns to booktech@oreilly.com.