High Quality Code – Style Matters

Chapter 5. Design in Construction Chapter 31. Layout and Style

Software Constructionby Jeff Nogy

Chapter 5. Design in Construction

Introduction 5.1. Design Challenges 5.2. Key Design Concepts 5.3. Design Building Blocks: Heuristics 5.4. Design Practices 5.5. Comments on Popular Methodologies

Introduction - Code Complete

5. Introduction

Process of building The hands-on part Coding or Programming Construction = Programming

5.1. Design Challenges

Design Is a Wicked Problem Wicked problem Solve the problem once, then solve it again Tacoma Narrows Bridge

Design Is a Sloppy Process (Even If it Produces a Tidy Result) False steps and go down many blind alleys Good Enough?

5.1. Design Challenges

Design Is About Tradeoffs and Priorities Ideal world vs. Real world

Design Involves Restrictions Create possibilities and Restrict

possibilities

5.1. Design Challenges

Design Is Nondeterministic More than one way to skin a cat

Design Is a Heuristic Process Trial and Error

Design Is Emergent Evolve and Improve

5.2. Key Design Concepts

Software's Primary Technical Imperative: Managing Complexity Essential and Accidental Difficulties Importance of Managing Complexity How to Attack Complexity

5.2. Key Design Concepts

Desirable Characteristics of a Design Levels of Design

Level 1: Software System Level 2: Division into Subsystems or

Packages Level 3: Division into Classes Level 4: Division into Routines Level 5: Internal Routine Design

5.3. Design Building Blocks: Heuristics

Find Real-World Objects Form Consistent Abstractions Encapsulate Implementation Details Inherit—When Inheritance Simplifies

the Design

5.3. Design Building Blocks: Heuristics

Hide Secrets (Information Hiding) Secrets and the Right to Privacy Value of Information Hiding

Identify Areas Likely to Change Keep Coupling Loose

Coupling Criteria Kinds of Coupling

5.3. Design Building Blocks: Heuristics

Look for Common Design Patterns Patterns provide several benefits

Other Heuristics Things to aim for

Guidelines for Using Heuristics

5.4. Design Practices

Iterate Divide and Conquer Top-Down and Bottom-Up Design

Approaches Experimental Prototyping

5.4. Design Practices

Collaborative Design How Much Design Is Enough? Capturing Your Design Work

5.5. Comments on Popular Methodologies

“Treat design as a wicked, sloppy, heuristic process. Don't settle for the first design that occurs to you. Collaborate. Strive for simplicity. Prototype when you need to. Iterate, iterate, and iterate again. You'll be happy with your designs.”

Chapter 31. Layout and Style Introduction 31.1. Layout Fundamentals 31.2. Layout Techniques 31.3. Layout Styles 31.4. Laying Out Control Structures 31.5. Laying Out Individual Statements 31.6. Laying Out Comments 31.7. Laying Out Routines 31.8. Laying Out Classes

Introduction

Layout of program source code Execution speed, memory use Understand the code Others to read

31.1. Layout Fundamentals

Layout Extremes: Listing 31-1/* Use the insertion sort technique to sort the "data" array in ascending order. This routine assumes that data[ firstElement ] is not the first element in data and that data[ firstElement-1 ] can be accessed. */ public void InsertionSort( int[] data, int firstElement, int lastElement ) { /* Replace element at lower boundary with an element guaranteed to be first in a sorted list. */ int lowerBoundary = data[ firstElement-1 ]; data[ firstElement-1 ] = SORT_MIN; /* The elements in positions firstElement through sortBoundary-1 are always sorted. In each pass through the loop, sortBoundary is increased, and the element at the position of the new sortBoundary probably isn't in its sorted place in the array, so it's inserted into the proper place somewhere between firstElement and sortBoundary. */ for (int sortBoundary = firstElement+1; sortBoundary <= lastElement; sortBoundary++ ) { int insertVal = data[ sortBoundary ]; int insertPos = sortBoundary; while (insertVal < data[ insertPos-1 ] ) { data[ insertPos ] = data[ insertPos-1 ]; insertPos = insertPos-1; } data[ insertPos ] = insertVal; } /* Replace original lower-boundary element */ data[ firstElement-1 ] = lowerBoundary; }

31.1. Layout Fundamentals

Layout Extremes: Listing 31-3/* Use the insertion sort technique to sort the "data" array in ascendingorder. This routine assumes that data[ firstElement ] is not thefirst element in data and that data[ firstElement-1 ] can be accessed.*/

public void InsertionSort( int[] data, int firstElement, int lastElement ) { // Replace element at lower boundary with an element guaranteed to be // first in a sorted list. int lowerBoundary = data[ firstElement-1 ]; data[ firstElement-1 ] = SORT_MIN;

/* The elements in positions firstElement through sortBoundary-1 are always sorted. In each pass through the loop, sortBoundary is increased, and the element at the position of the new sortBoundary probably isn't in its sorted place in the array, so it's inserted into the proper place somewhere between firstElement and sortBoundary. */ for ( int sortBoundary = firstElement + 1; sortBoundary <= lastElement; sortBoundary++ ) { int insertVal = data[ sortBoundary ]; int insertPos = sortBoundary; while ( insertVal < data[ insertPos - 1 ] ) { data[ insertPos ] = data[ insertPos - 1 ]; insertPos = insertPos - 1; } data[ insertPos ] = insertVal; }

// Replace original lower-boundary element data[ firstElement - 1 ] = lowerBoundary;}

31.1. Layout Fundamentals

The Fundamental Theorem of Formatting

Human and Computer Interpretations of a Program x = 3+4 * 2+7;

How Much Is Good Layout Worth? “Exploratory Experiments in Programmer

Behavior” by Ben Shneiderman (1976).

31.1. Layout Fundamentals

Layout as Religion Objectives of Good Layout

How to Put the Layout Objectives to Use

31.2. Layout Techniques

White Space Usewhitespacetoenhancereadability

Grouping Blank lines Indentation

Parentheses

31.3. Layout Styles

Pure Blocks

Emulating Pure Blocks

Using begin-end Pairs (Braces) to Designate Block Boundaries

31.3. Layout Styles

Endline Layout

Which Style Is Best?

While ( pixelColor = Color_Red ) statement1; statement2; ... Wend

31.4. Laying Out Control Structures

Fine Points of Formatting Control-Structure Blocks

Other Considerations

31.5. Laying Out Individual Statements

Statement Length Using Spaces for Clarity Formatting Continuation Lines Using Only One Statement Per Line Laying Out Data Declarations

31.6. Laying Out Comments

Indent a comment with its corresponding code

Set off each comment with at least one blank line

For transactionId = 1 To totalTransactions ' get transaction data GetTransactionType( transactionType ) GetTransactionAmount( transactionAmount )

' process transaction based on transaction type If transactionType = Transaction_Sale Then AcceptCustomerSale( transactionAmount )

// comment zeroCodeStatementZero;CodeStatementOne;

// comment oneCodeStatementTwo;CodeStatementThree;

31.7. Laying Out Routines

Use blank lines to separate parts of a routine

Use standard indentation for routine arguments

public bool ReadEmployeeData( int maxEmployees, EmployeeList *employees, EmployeeFile *inputFile, int *employeeCount, bool *isInputError)...

public void InsertionSort( SortArray data, int firstElement, int lastElement)

31.8. Laying Out Classes

Laying Out Class Interfaces Laying Out Class Implementations Laying Out Files and Programs

Conclusion Software complexity Simplicity is achieved in two general ways Design is heuristic Good design is iterative Information hiding The first priority of visual layout Looking good is secondary Pure blocks and Pure-block emulation Structuring code is important Religious issues