The Robert C. Martin Clean Code Collection Upper Saddle River, NJ • Boston • Indianapolis • San Francisco New York • Toronto • Montreal • London • Munich • Paris • Madrid Cape Town • Sydney • Tokyo • Singapore • Mexico City Note from the Publisher The Robert C. Martin Clean Code Collection consists of two bestselling eBooks: • Clean Code:A Handbook of Agile Software Craftmanship • The Clean Coder:A Code of Conduct for Professional Programmers In this collection, Robert C. Martin, also known as “Uncle Bob,” provides a pragmatic method for writing better code from the start. He reveals the disciplines, techniques, tools, and practices that separate software craftsmen from mere “9-to-5” programmers. Within this collection are the tools and methods you need to become a true software professional. To simplify access to each book, we’ve appended “A” to the pages of Clean Code:A Handbook of Agile Software Craftmanship, and “B” to pages of The Clean Coder:A Code of Conduct for Professional Programmers.This enabled us to produce a single, comprehensive table of contents and dedicated indexes. We hope you find this collection useful! —The editorial and production teams at Prentice Hall Many of the designations used by manufacturers and sellers to distinguish their products are claimed as trademarks.Where those designations appear in this book, and the pub- lisher was aware of a trademark claim, the designations have been printed with initial capital letters or in all capitals. The author and publisher have taken care in the preparation of this book, but make no expressed or implied warranty of any kind and assume no responsibility for errors or omissions. No liability is assumed for incidental or consequential damages in connection with or arising out of the use of the information or programs contained herein. The publisher offers excellent discounts on this book when ordered in quantity for bulk purchases or special sales, which may include electronic versions and/or custom covers and content particular to your business, training goals, marketing focus, and branding interests. For more information, please contact: U.S. Corporate and Government Sales (800) 382-3419 [email protected] For sales outside the United States, please contact: International Sales [email protected] Visit us on the Web: informit.com/ph Copyright © 2012 Pearson Education, Inc. All rights reserved. Printed in the United States of America.This publication is protected by copyright, and permission must be obtained from the publisher prior to any prohibit- ed reproduction, storage in a retrieval system, or transmission in any form or by any means, electronic, mechanical, photocopying, recording, or likewise.To obtain permission to use material from this work, please submit a written request to Pearson Education, Inc., Permissions Department, One Lake Street, Upper Saddle River, New Jersey 07458, or you may fax your request to (201) 236-3290. ISBN-13: 978-0-13-292847-2 ISBN-10: 0-13-292847-7 Table of Contents CLEAN CODE 1 Clean Code . .1A There Will Be Code . .2A Bad Code . .3A The Total Cost of Owning a Mess . .4A The Grand Redesign in the Sky . .5A Attitude . .5A The Primal Conundrum . .6A The Art of Clean Code? . .6A What Is Clean Code? . .7A Schools of Thought . .12A We Are Authors . .13A The Boy Scout Rule . .14A Prequel and Principles . .15A Conclusion . .15A Bibliography . .15A 2 Meaningful Names . .17A Introduction . .17A Use Intention-Revealing Names . .18A Avoid Disinformation . .19A Make Meaningful Distinctions . .20A Use Pronounceable Names . .21A Use Searchable Names . .22A Avoid Encodings . .23A Hungarian Notation . .23A Member Prefixes . .24A Interfaces and Implementations . .24A Avoid Mental Mapping . .25A Class Names . .25A Method Names . .25A Don’t Be Cute . .26A Pick One Word per Concept . .26A Don’t Pun . .26A Use Solution Domain Names . .27A Use Problem Domain Names . .27A Add Meaningful Context . .27A Don’t Add Gratuitous Context . .29A Final Words . .30A 3 Functions . .31A Small! . .34A Blocks and Indenting . .35A Do One Thing . .35A Sections within Functions . .36A One Level of Abstraction per Function . .36A Reading Code from Top to Bottom: The Stepdown Rule . .37A Switch Statements . .37A Use Descriptive Names . .39A Function Arguments . .40A Common Monadic Forms . .41A Flag Arguments . .41A Dyadic Functions . .42A Triads . .42A Argument Objects . .43A Argument Lists . .43A Verbs and Keywords . .43A Have No Side Effects . .44A Output Arguments . .45A Command Query Separation . .45A Prefer Exceptions to Returning Error Codes . .46A Extract Try/Catch Blocks . .46A Error Handling Is One Thing . .47A The Error.java Dependency Magnet . .47A Don’t Repeat Yourself . .48A Structured Programming . .48A How Do You Write Functions Like This? . .49A Conclusion . .49A SetupTeardownIncluder . .50A Bibliography . .52A vi Contents 4 Comments . .53A Comments Do Not Make Up for Bad Code . .55A Explain Yourself in Code . .55A Good Comments . .55A Legal Comments . .55A Informative Comments . .56A Explanation of Intent . .56A Clarification . .57A Warning of Consequences . .58A TODO Comments . .58A Amplification . .59A Javadocs in Public APIs . .59A Bad Comments . .59A Mumbling . .59A Redundant Comments . .60A Misleading Comments . .63A Mandated Comments . .63A Journal Comments . .63A Noise Comments . .64A Scary Noise . .66A Don’t Use a Comment When You Can Use a Function or a Variable . .67A Position Markers . .67A Closing Brace Comments . .67A Attributions and Bylines . .68A Commented-Out Code . .68A HTML Comments . .69A Nonlocal Information . .69A Too Much Information . .70A Inobvious Connection . .70A Function Headers . .70A Javadocs in Nonpublic Code . .71A Example . .71A Bibliography . .74A 5 Formatting . .75A The Purpose of Formatting . .76A Vertical Formatting . .76A Contents vii The Newspaper Metaphor . .77A Vertical Openness Between Concepts . .78A Vertical Density . .79A Vertical Distance . .80A Vertical Ordering . .84A Horizontal Formatting . .85A Horizontal Openness and Density . .86A Horizontal Alignment . .87A Indentation . .88A Dummy Scopes . .90A Team Rules . .90A Uncle Bob’s Formatting Rules . .90A 6 Objects and Data Structures . .93A Data Abstraction . .93A Data/Object Anti-Symmetry . .95A The Law of Demeter . .97A Train Wrecks . .98A Hybrids . .99A Hiding Structure . .99A Data Transfer Objects . .100A Active Record . .101A Conclusion . .101A Bibliography . .101A 7 Error Handling . .103A Use Exceptions Rather Than Return Codes . .104A.