- Code Complete, Second Edition
- Preface
- Acknowledgments
- About the Author
- I. Laying the Foundation
- 1. Welcome to Software Construction
- 2. Metaphors for a Richer Understanding of Software Development
- 3. Measure Twice, Cut Once: Upstream Prerequisites
- 3.1. Importance of Prerequisites
- 3.2. Determine the Kind of Software You're Working On
- 3.3. Problem-Definition Prerequisite
- 3.4. Requirements Prerequisite
- 3.5. Architecture Prerequisite
- Typical Architectural Components
- Program Organization
- Major Classes
- Data Design
- Business Rules
- User Interface Design
- Resource Management
- Security
- Performance
- Scalability
- Interoperability
- Internationalization/Localization
- Input/Output
- Error Processing
- Fault Tolerance
- Architectural Feasibility
- Overengineering
- Buy-vs.-Build Decisions
- Reuse Decisions
- Change Strategy
- General Architectural Quality
- Typical Architectural Components
- 3.6. Amount of Time to Spend on Upstream Prerequisites
- Additional Resources
- Key Points
- 4. Key Construction Decisions
- II. Creating High-Quality Code
- 5. Design in Construction
- 5.1. Design Challenges
- 5.2. Key Design Concepts
- 5.3. Design Building Blocks: Heuristics
- Find Real-World Objects
- Form Consistent Abstractions
- Encapsulate Implementation Details
- Inherit—When Inheritance Simplifies the Design
- Hide Secrets (Information Hiding)
- Identify Areas Likely to Change
- Keep Coupling Loose
- Look for Common Design Patterns
- Other Heuristics
- Summary of Design Heuristics
- Guidelines for Using Heuristics
- 5.4. Design Practices
- 5.5. Comments on Popular Methodologies
- Additional Resources
- Key Points
- 6. Working Classes
- 7. High-Quality Routines
- 8. Defensive Programming
- 8.1. Protecting Your Program from Invalid Inputs
- 8.2. Assertions
- 8.3. Error-Handling Techniques
- 8.4. Exceptions
- 8.5. Barricade Your Program to Contain the Damage Caused by Errors
- 8.6. Debugging Aids
- 8.7. Determining How Much Defensive Programming to Leave in Production Code
- 8.8. Being Defensive About Defensive Programming
- Additional Resources
- Key Points
- 9. The Pseudocode Programming Process
- 5. Design in Construction
- III. Variables
- 10. General Issues in Using Variables
- 11. The Power of Variable Names
- 12. Fundamental Data Types
- 13. Unusual Data Types
- IV. Statements
- 14. Organizing Straight-Line Code
- 15. Using Conditionals
- 16. Controlling Loops
- 17. Unusual Control Structures
- 18. Table-Driven Methods
- 19. General Control Issues
- 19.1. Boolean Expressions
- Using true and false for Boolean Tests
- Making Complicated Expressions Simple
- Forming Boolean Expressions Positively
- Using Parentheses to Clarify Boolean Expressions
- Knowing How Boolean Expressions Are Evaluated
- Writing Numeric Expressions in Number-Line Order
- Guidelines for Comparisons to 0
- Common Problems with Boolean Expressions
- 19.2. Compound Statements (Blocks)
- 19.3. Null Statements
- 19.4. Taming Dangerously Deep Nesting
- 19.5. A Programming Foundation: Structured Programming
- 19.6. Control Structures and Complexity
- Key Points
- 19.1. Boolean Expressions
- V. Code Improvements
- 20. The Software-Quality Landscape
- 21. Collaborative Construction
- 22. Developer Testing
- 23. Debugging
- 24. Refactoring
- 25. Code-Tuning Strategies
- 26. Code-Tuning Techniques
- VI. System Considerations
- 27. How Program Size Affects Construction
- 28. Managing Construction
- 29. Integration
- 30. Programming Tools
- VII. Software Craftsmanship
- 31. Layout and Style
- 32. Self-Documenting Code
- 32.1. External Documentation
- 32.2. Programming Style as Documentation
- 32.3. To Comment or Not to Comment
- 32.4. Keys to Effective Comments
- 32.5. Commenting Techniques
- 32.6. IEEE Standards
- Additional Resources
- Key Points
- 33. Personal Character
- 33.1. Isn't Personal Character Off the Topic?
- 33.2. Intelligence and Humility
- 33.3. Curiosity
- 33.4. Intellectual Honesty
- 33.5. Communication and Cooperation
- 33.6. Creativity and Discipline
- 33.7. Laziness
- 33.8. Characteristics That Don't Matter As Much As You Might Think
- 33.9. Habits
- Additional Resources
- Key Points
- 34. Themes in Software Craftsmanship
- 34.1. Conquer Complexity
- 34.2. Pick Your Process
- 34.3. Write Programs for People First, Computers Second
- 34.4. Program into Your Language, Not in It
- 34.5. Focus Your Attention with the Help of Conventions
- 34.6. Program in Terms of the Problem Domain
- 34.7. Watch for Falling Rocks
- 34.8. Iterate, Repeatedly, Again and Again
- 34.9. Thou Shalt Rend Software and Religion Asunder
- Key Points
- 35. Where to Find More Information
- Bibliography
- Index
- About the Author
In addition to the IEEE standards, numerous other resources are available on program documentation.
Spinellis, Diomidis. Code Reading: The Open Source Perspective. Boston, MA: Addison-Wesley, 2003. This book is a pragmatic exploration of techniques for reading code, including where to find code to read, tips for reading large code bases, tools that support code reading, and many other useful suggestions.
SourceForge.net. For decades, a perennial problem in teaching software development has been finding life-size examples of production code to share with students. Many people learn quickest from studying real-life examples, but most life-size code bases are treated as proprietary information by the companies that created them. This situation has improved dramatically through the combination of the Internet and opensource software. The Source Forge website contains code for thousands of programs in C, C++, Java, Visual Basic, PHP, Perl, Python, and many other languages, all which you can download for free. Programmers can benefit from wading through the code on the website to see much larger real-world examples than Code Complete, Second Edition, is able to show in its short code examples. Junior programmers who haven't previously seen extensive examples of production code will find this website especially valuable as a source of both good and bad coding practices.
I wonder how many great novelists have never read someone else's work, how many great painters have never studied another's brush strokes, how many skilled surgeons never learned by looking over a colleague's shoulder…. And yet that's what we expect programmers to do.
Sun Microsystems. "How to Write Doc Comments for the Javadoc Tool," 2000. Available from http://java.sun.com/j2se/javadoc/writingdoccomments/. This article describes how to use Javadoc to document Java programs. It includes detailed advice about how to tag comments by using an @tag style notation. It also includes many specific details about how to wordsmith the comments themselves. The Javadoc conventions are probably the most fully developed code-level documentation standards currently available.
Here are sources of information on other topics in software documentation:
McConnell, Steve. Software Project Survival Guide. Redmond, WA: Microsoft Press, 1998. This book describes the documentation required by a medium-sized businesscritical project. A related website provides numerous related document templates.
http://www.construx.com. This website (my company's website) contains numerous document templates, coding conventions, and other resources related to all aspects of software development, including software documentation.
Post, Ed. "Real Programmers Don't Use Pascal," Datamation, July 1983, pp. 263–265. This tongue-in-cheek paper argues for a return to the "good old days" of Fortran programming when programmers didn't have to worry about pesky issues like readability.
Good Commenting Technique
Can someone pick up the code and immediately start to understand it?
Do comments explain the code's intent or summarize what the code does, rather than just repeating the code?
Is the Pseudocode Programming Process used to reduce commenting time?
Has tricky code been rewritten rather than commented?
Are comments up to date?
Are comments clear and correct?
Does the commenting style allow comments to be easily modified?
Statements and Paragraphs
Does the code avoid endline comments?
Do comments focus on why rather than how?
Do comments prepare the reader for the code to follow?
Does every comment count? Have redundant, extraneous, and self-indulgent comments been removed or improved?
Are surprises documented?
Have abbreviations been avoided?
Is the distinction between major and minor comments clear?
Is code that works around an error or undocumented feature commented?
Data Declarations
Are units on data declarations commented?
Are the ranges of values on numeric data commented?
Are coded meanings commented?
Are limitations on input data commented?
Are flags documented to the bit level?
Has each global variable been commented where it is declared?
Has each global variable been identified as such at each usage, by a naming convention, a comment, or both?
Are magic numbers replaced with named constants or variables rather than just documented?
Is each control statement commented?
Are the ends of long or complex control structures commented or, when possible, simplified so that they don't need comments?
Routines
Is the purpose of each routine commented?
Are other facts about each routine given in comments, when relevant, including input and output data, interface assumptions, limitations, error corrections, global effects, and sources of algorithms?
Files, Classes, and Programs
Does the program have a short document, such as that described in the Book Paradigm, that gives an overall view of how the program is organized?
Is the purpose of each file described?
Are the author's name, e-mail address, and phone number in the listing?
-
No Comment