You are previewing Code Craft.
O'Reilly logo
Code Craft

Book Description

Many programmers know how to write correct code - code that works. But not all know how to craft great code - code that is well written and easy to understand. Code Craft teaches programmers how to move beyond writing correct code to writing great code. The book covers code writing concerns, including code presentation style, variable naming, error handling, and security; and the wider issues of programming in the real world, such as good teamwork, development processes, and documentation. Code Craft presents language-agnostic advice that is relevant to all developers, from an author with loads of practical experience. A Q&A section at the end of each chapter helps readers to review the material and makes the book suited for academic use as well.

Table of Contents

  1. Code Craft
    1. ADVANCE PRAISE FOR CODE CRAFT
    2. PREFACE
      1. What's In It for Me?
      2. Getting Better
      3. Who Should Read This Book?
      4. What's Covered?
      5. How This Book is Organized
      6. The Chapters—a Closer Look
      7. How to Use This Book
        1. A Note to Mentors
    3. ACKNOWLEDGMENTS
    4. About the Author
    5. ABOUT THE AUTHOR
    6. I. AT THE CODEFACE
      1. 1. ON THE DEFENSIVE
        1. Toward Good Code
        2. Assume the Worst
        3. What Is Defensive Programming?
        4. The Big, Bad World
          1. Techniques for Defensive Programming
          2. Employ a Good Coding Style and Sound Design
          3. Don't Code in a Hurry
          4. Trust No One
          5. Write Code for Clarity, Not Brevity
          6. Don't Let Anyone Tinker with Stuff They Shouldn't
          7. Compile with All Warnings Switched On
          8. Use Static Analysis Tools
          9. Use Safe Data Structures
          10. Check Every Return Value
          11. Handle Memory (and Other Precious Resources) Carefully
          12. Initialize All Variables at Their Points of Declaration
          13. Declare Variables as Late as Possible
          14. Use Standard Language Facilities
          15. Use a Good Diagnostic Logging Facility
          16. Cast Carefully
          17. The Fine Print
          18. Constraints
          19. What to Constrain
          20. Removing Constraints
        5. In a Nutshell
        6. See Also
        7. Get Thinking
          1. Mull It Over
          2. Getting Personal
      2. 2. THE BEST LAID PLANS
        1. What's the Big Deal?
        2. Know Your Audience
        3. What Is Good Presentation?
        4. Brace Yourself
          1. K&R Brace Style
          2. Exdented Brace Style
          3. Indented Brace Style
          4. Other Brace Styles
        5. One Style to Rule Them All
        6. House Styles (and Where to Stick Them)
        7. Setting the Standard
        8. Righteous Wars?
        9. In a Nutshell
        10. See Also
        11. Get Thinking
          1. Mull It Over
          2. Getting Personal
      3. 3. WHAT'S IN A NAME?
        1. Why Should We Name Well?
        2. What Do We Name?
        3. Name Games
          1. Descriptive
          2. Technically Correct
          3. Idiomatic
          4. Appropriate
        4. The Nuts and Bolts
          1. Naming Variables
          2. Naming Functions
          3. Naming Types
          4. Naming Namespaces
          5. Naming Macros
          6. Naming Files
        5. A Rose by Any Other Name
          1. Be Consistent
          2. Exploit Context
          3. Use Names to Your Advantage
        6. In a Nutshell
        7. See Also
        8. Get Thinking
          1. Mull It Over
          2. Getting Personal
      4. 4. THE WRITESTUFF
        1. Self-Documenting Code
        2. Techniques for Self-Documenting Code
          1. Write Simple Code with Good Presentation
          2. Choose Meaningful Names
          3. Decompose into Atomic Functions
          4. Choose Descriptive Types
          5. Name Constants
          6. Emphasize Important Code
          7. Group-Related Information
          8. Provide a File Header
          9. Handle Errors Appropriately
          10. Write Meaningful Comments
        3. Practical Self-Documentation Methodologies
          1. Literate Programming
          2. Documentation Tools
        4. In a Nutshell
        5. See Also
        6. Get Thinking
          1. Mull It Over
          2. Getting Personal
      5. 5. A PASSING COMMENT
        1. What Is a Code Comment?
        2. What Do Comments Look Like?
        3. How Many Comments?
        4. What Goes Inside Our Comments?
          1. Explain Why, Not How
          2. Don't Describe the Code
          3. Don't Replace Code
          4. Keep It Useful
          5. Avoid Distractions
        5. In Practice
        6. A Comment on Aesthetics
          1. Consistency
          2. Clear Block Comments
          3. Indenting Comments
          4. End-of-Line Comments
          5. Helping You to Read the Code
          6. Choose a Low-Maintenance Style
          7. Breakwaters
          8. Flags
          9. File Header Comments
        7. Working with Comments
          1. Helping You to Write Routines
          2. Bug-Fix Notices
          3. Comment Rot
          4. Maintenance and the Inane Comment
        8. In a Nutshell
        9. See Also
        10. Get Thinking
          1. Mull It Over
          2. Getting Personal
      6. 6. TO ERR IS HUMAN
        1. From Whence It Came
        2. Error-Reporting Mechanisms
          1. No Reporting
          2. Return Values
          3. Error Status Variables
          4. Exceptions
          5. Signals
        3. Detecting Errors
        4. Handling Errors
          1. When to Deal with Errors
          2. Possible Reactions
          3. Code Implications
        5. Raising Hell
        6. Managing Errors
        7. In a Nutshell
        8. See Also
        9. Get Thinking
          1. Mull It Over
          2. Getting Personal
    7. II. THE SECRET LIFE OF CODE
      1. 7. THE PROGRAMMER'S TOOLBOX
        1. What Is a Software Tool?
        2. Why Worry About Tools?
        3. Power Tools
          1. Understand What It Can Do
          2. Learn How to Drive it
          3. Know What Tasks It's Good For
          4. Check That It's Working
          5. Have a Clear Route to Find Out More
          6. Find Out When New Versions Appear
        4. Which Tools?
          1. Source Editing Tools
            1. Source Code Editor
            2. Source Manipulation Tools
            3. Source Navigation Tools
            4. Revision Control
            5. Source Generation
            6. Source Beautifiers
          2. Code Construction Tools
            1. Compiler
            2. Linker
            3. Build Environment
            4. Testing Toolchain
          3. Debugging and Investigative Tools
            1. Debugger
            2. Profiler
            3. Code Validators
            4. Metrics Tools
            5. Disassembler
            6. Fault Tracking
          4. Language Support Tools
            1. The Language
            2. Run Time and Interpreter
            3. Components and Libraries
          5. Miscellaneous Tools
            1. Documentation Tools
            2. Project Management
        5. In a Nutshell
        6. See Also
        7. Get Thinking
          1. Mull It Over
          2. Getting Personal
      2. 8. TESTING TIMES
        1. Reality Check
        2. Who, What, When, and Why?
          1. Why We Test
          2. Who Tests
          3. What Testing Involves
          4. When We Test
        3. Testing Isn't Hard . . .
        4. The Types of Test
        5. Choosing Unit Test Cases
        6. Design for Test
        7. Look! No Hands!
        8. The Face of Failure
        9. Can You Manage It?
          1. Fault-Tracking System
          2. Bug Reviews
        10. In a Nutshell
        11. See Also
        12. Get Thinking
          1. Mull It Over
          2. Getting Personal
      3. 9. FINDING FAULT
        1. The Facts of Life
        2. Nature of the Beast
          1. The View from 1,000 Feet
          2. The View from the Ground
          3. The View from the Trenches
        3. Pest Extermination
          1. The Low Road
          2. The High Road
        4. Bug Hunting
          1. Compile-Time Errors
          2. Run-Time Errors
            1. Identify a Failure
            2. Reproduce It
            3. Locate the Fault
            4. Understand the Problem
            5. Create a Test
            6. Fix the Fault
            7. Prove You've Fixed It
            8. If All Else Fails
        5. How to Fix Faults
        6. Prevention
        7. Wasp Spray, Slug Repellent, Fly Paper . . .
          1. Debugger
          2. Memory Access Validator
          3. System Call Tracing
          4. Core Dump
          5. Logging
            1. Static Analyzer
        8. In a Nutshell
        9. See Also
        10. Get Thinking
          1. Mull It Over
          2. Getting Personal
      4. 10. THE CODE THAT JACK BUILT
        1. Language Barriers
          1. Interpreted Languages
          2. Compiled Languages
          3. Byte-Compiled Languages
        2. Making Mountains out of Molehills
        3. Building Builds
        4. What Makes a Good Build System?
          1. Simplicity
          2. Uniformity
          3. Repeatable and Reliable
          4. Atomic
          5. Coping with Errors
        5. The Mechanics
          1. Choice of Targets
          2. Housekeeping
          3. Dependencies
          4. Automated Builds
          5. Build Configuration
          6. Recursive Make
        6. Please Release Me
        7. Jack-of-All-Trades, Buildmaster Of?
        8. In a Nutshell
        9. See Also
        10. Get Thinking
          1. Mull It Over
          2. Getting Personal
      5. 11. THE NEED FOR SPEED
        1. What Is Optimization?
        2. What Makes Code Suboptimal?
        3. Why Not Optimize?
          1. Alternatives
        4. Why Optimize?
        5. The Nuts and Bolts
          1. Prove You Need to Optimize
          2. Identify the Slowest Code
          3. Testing the Code
          4. Optimizing the Code
          5. After Optimization
        6. Optimization Techniques
          1. Design Changes
          2. Code Changes
        7. Writing Efficient Code
        8. In a Nutshell
        9. See Also
        10. Get Thinking
          1. Mull It Over
          2. Getting Personal
      6. 12. AN INSECURITY COMPLEX
        1. The Risks
        2. The Opposition
        3. Excuses, Excuses
        4. Feeling Vulnerable
          1. Insecure Design and Architecture
          2. Buffer Overrun
          3. Embedded Query Strings
          4. Race Conditions
          5. Integer Overflow
        5. Protection Racket
          1. System Installation Techniques
          2. Software Design Techniques
          3. Code Implementation Techniques
          4. Procedural Techniques
        6. In a Nutshell
        7. See Also
        8. Get Thinking
          1. Mull It Over
          2. Getting Personal
    8. III. THE SHAPE OF CODE
      1. 13. GRAND DESIGNS
        1. Programming as Design
        2. What Do We Design?
        3. What's All the Fuss About?
        4. Good Software Design
          1. Simplicity
          2. Elegance
          3. Modularity
          4. Good Interfaces
          5. Extensibility
          6. Avoid Duplication
          7. Portability
          8. Idiomatic
          9. Well-Documented
        5. How to Design Code
          1. Design Methods and Processes
          2. Design Tools
        6. In a Nutshell
        7. See Also
        8. Get Thinking
          1. Mull It Over
          2. Getting Personal
      2. 14. SOFTWARE ARCHITECTURE
        1. What Is Software Architecture?
          1. Software Blueprints
          2. Points of View
          3. Where and When Do You Do It?
          4. What Is It Used For?
          5. Of Components and Connections
            1. Components
            2. Connections
        2. What Is Good Architecture?
        3. Architectural Styles
          1. No Architecture
          2. Layered Architecture
          3. Pipe and Filter Architecture
          4. Client/Server Architecture
          5. Component-Based Architecture
          6. Frameworks
        4. In a Nutshell
        5. See Also
        6. Get Thinking
          1. Mull It Over
          2. Getting Personal
      3. 15. SOFTWARE EVOLUTION OR SOFTWARE REVOLUTION?
        1. Software Rot
        2. The Warning Signs
        3. How Does Code Grow?
        4. Believe the Impossible
        5. What Can We Do About This?
          1. Writing New Code
          2. Maintenance of Existing Code
        6. In a Nutshell
        7. See Also
        8. Get Thinking
          1. Mull It Over
          2. Getting Personal
    9. IV. A HERD OF PROGRAMMERS?
      1. 16. CODE MONKEYS
        1. Monkey Business
          1. The Eager Coder
          2. The Code Monkey
          3. The Guru
          4. The Demiguru
          5. The Arrogant Genius
          6. The Cowboy
          7. The Planner
          8. The Old Timer
          9. The Zealot
          10. The Monocultured Programmer
          11. The Slacker
          12. The Reluctant Team Leader
          13. You
        2. The Ideal Programmer
        3. So What?
        4. The Stupidest of Men
        5. In a Nutshell
        6. See Also
        7. Action Sheet
        8. Get Thinking
          1. Mull It Over
          2. Getting Personal
      2. 17. TOGETHER WE STAND
        1. Our Teams—The Big Picture
        2. Team Organization
          1. Management Approach
          2. Division of Responsibility
          3. Organization and Code Structure
        3. Teamwork Tools
        4. Team Diseases
          1. Tower of Babel
          2. Dictatorship
          3. Development Democracy
          4. Satellite Station
          5. The Grand Canyon
          6. Quicksand
          7. Lemmings
        5. Personal Skills and Characteristics for Good Teamwork
          1. Communication
          2. Humility
          3. Dealing with Conflict
          4. Learning and Adaptability
          5. Know Your Limitations
        6. Teamwork Principles
          1. Collective Code Ownership
          2. Respect Other People's Code
          3. Code Guidelines
          4. Define Success
          5. Define Responsibility
          6. Avoid Burnout
        7. The Team Life Cycle
          1. Team Creation
          2. Team Growth
            1. Inward Team Growth
            2. Outward Team Growth
          3. Teamwork
          4. Team Closure
        8. In a Nutshell
        9. See Also
        10. Action Sheet
        11. Get Thinking
          1. Mull It Over
          2. Getting Personal
      3. 18. PRACTICING SAFE SOURCE
        1. Our Responsibility
        2. Source Control
          1. Revision Control
          2. Access Control
          3. Working with the Repository
          4. Leave Branching to the Trees
          5. A Brief History of Source Control
        3. Configuration Management
        4. Backups
        5. Releasing Source Code
        6. Wherever I Lay My Source
        7. In a Nutshell
        8. See Also
        9. Get Thinking
          1. Mull It Over
          2. Getting Personal
    10. V. PART OF THE PROCESS
      1. 19. BEING SPECIFIC
        1. What Are They, Specifically?
        2. The Types of Specification
          1. Requirements Specification
          2. Functional Specification
          3. System Architecture Specification
          4. User Interface Specification
          5. Design Specification
          6. Test Specification
        3. What Should Specifications Contain?
        4. The Specification-Writing Process
        5. Why Don't We Write Specifications?
        6. In a Nutshell
        7. See Also
        8. Get Thinking
          1. Mull It Over
          2. Getting Personal
      2. 20. A REVIEW TO A KILL
        1. What Is a Code Review?
        2. When Do You Review?
          1. Whether to Review
          2. Which Code to Review
        3. Performing Code Reviews
          1. Code Review Meetings
            1. Where?
            2. When?
            3. Roles and Responsibilities
            4. Agenda
          2. Integration Reviews
        4. Review Your Attitudes
          1. The Author's Attitude
          2. The Reviewer's Attitude
        5. Code Perfection
        6. Beyond the Code Review
        7. In a Nutshell
        8. See Also
        9. Checklist
        10. Get Thinking
          1. Mull It Over
          2. Getting Personal
      3. 21. HOW LONG IS A PIECE OF STRING?
        1. A Stab in the Dark
        2. Why Is Estimation So Hard?
        3. Under Pressure
        4. Practical Ways to Estimate
        5. The Planning Game
        6. Keep Up!
        7. In a Nutshell
        8. See Also
        9. Get Thinking
          1. Mull It Over
          2. Getting Personal
    11. VI. VIEW FROM THE TOP
      1. 22. RECIPE FOR A PROGRAM
        1. Programming Styles
          1. Structured Programming
          2. Object-Oriented Programming
          3. Functional Programming
          4. Logic Programming
        2. Recipes: The How and the What
        3. Development Processes
          1. Ad Hoc
          2. Waterfall Model
          3. SSADM and PRINCE
          4. V Model
          5. Prototyping
          6. Iterative and Incremental Development
          7. Spiral Model
          8. Agile Methodologies
          9. Other Development Processes
        4. Enough, Already!
        5. Pick a Process
        6. In a Nutshell
        7. See Also
        8. Get Thinking
          1. Mull It Over
          2. Getting Personal
      2. 23. THE OUTER LIMITS
        1. Applications Programming
          1. Shrink-Wrap Software
          2. Custom Applications
        2. Games Programming
        3. Systems Programming
        4. Embedded Programming
        5. Distributed Programming
        6. Web Application Programming
        7. Enterprise Programming
        8. Numerical Programming
        9. So What?
        10. In a Nutshell
        11. See Also
        12. Get Thinking
          1. Mull It Over
          2. Getting Personal
      3. 24. WHERE NEXT?
        1. But What Now?
      4. A. Answers and Discussion
        1. Chapter 1: On the Defensive
          1. Mull It Over
          2. Getting Personal
        2. Chapter 2: The Best Laid Plans
          1. Mull It Over
          2. Getting Personal
        3. Chapter 3: What’s in a Name?
          1. Mull It Over
          2. Getting Personal
        4. Chapter 4: The Write Stuff
          1. Mull It Over
          2. Getting Personal
        5. Chapter 5: A Passing Comment
          1. Mull It Over
          2. Getting Personal
        6. Chapter 6: To Err Is Human
          1. Mull It Over
          2. Getting Personal
        7. Chapter 7: The Programmer’s Toolbox
          1. Mull It Over
          2. Getting Personal
        8. Chapter 8: Testing Times
          1. Mull It Over
          2. Getting Personal
        9. Chapter 9: Finding Fault
          1. Mull It Over
          2. Getting Personal
        10. Chapter 10: The Code That Jack Built
          1. Mull It Over
          2. Getting Personal
        11. Chapter 11: The Need for Speed
          1. Mull It Over
          2. Getting Personal
        12. Chapter 12: An Insecurity Complex
          1. Mull It Over
          2. Getting Personal
        13. Chapter 13: Grand Designs
          1. Mull It Over
          2. Getting Personal
        14. Chapter 14: Software Architecture
          1. Mull It Over
          2. Getting Personal
        15. Chapter 15: Software Evolution or Software Revolution?
          1. Mull It Over
          2. Getting Personal
        16. Chapter 16: Code Monkeys
          1. Mull It Over
        17. Chapter 17: Together We Stand
          1. Mull It Over
          2. Getting Personal
        18. Chapter 18: Practicing Safe Source
          1. Mull It Over
          2. Getting Personal
        19. Chatper 19: Being Specific
          1. Mull It Over
          2. Getting Personal
        20. Chapter 20: A Review to a Kill
          1. Mull It Over
          2. Getting Personal
        21. Chapter 21: How Long Is a Piece of String?
          1. Mull It Over
          2. Getting Personal
        22. Chapter 22: Recipe for a Program
          1. Mull It Over
          2. Getting Personal
        23. Chapter 23: The Outer Limits
          1. Mull It Over
          2. Getting Personal
      5. BIBLIOGRAPHY
    12. COLOPHON