高品質軟體的基本動作 101 for NTHU

高品質軟體的基本動作- 如何寫 "好的" 程式

Guidelines in How to Create High Quality Code

Johnson J. Su

自由軟體鑄造場 蘇展

2014/11/20

Code Complete 101

Johnson J. Su

Linkedin：https://www.linkedin.com/in/jansuE-mail：johnsonsu@iis.sinica.edu.tw

TEL： (02) 2788-3799 ext. 1478

In This Talk

• We will discuss• How to use Code Complete• What is high code quality• How to create high quality code

• We will not discuss• Part V - Code Improvement• Part VI - Software Craftsmanship• Detail of any programing language• Detail of how to deal with code• Any useful tools

Agenda

1. What is High Quality Code?

2. Variables (Good and Bad Examples)

3. Statements (Good and Bad Examples)

4. How to create High Quality Code?

Before we start…

Have you ever thought…?

• What are others’ code doing?

• Why others’ code looks like so dirty?

• How to improve/create high quality and more

readable code?

Have you ever thought…?

• 看不懂別人的 Code 在做什麼?

• 為什麼別人寫的 Code 很凌亂?

• 如何寫出 “品質好”, “可讀性高” 的 Code?

• Or more…?

Here’s your answer.

Guidance Code Complete 2nd

If you are…• Junior Developer

• Chapter 11, 18

• Senior Developer• Chapter 4~9

• Project Manager• Chapter 2, 33

• Standard Maker• Chapter 32

Guidance Code Complete 2nd

If you are…• Junior Developer

• Chapter 11, 18

• Senior Developer• Chapter 4~9

• Project Manager• Chapter 2, 33

• Standard Maker• Chapter 32

Agenda

1. What is High Quality Code?

2. Variables (Good and Bad Examples)

3. Statements (Good and Bad Examples)

4. How to create High Quality Code?

What is High Quality Code?

Software Quality?

Software Quality

External• Correctness• Usability• Efficiency• Reliability• Integrity• Adaptability• Accuracy• Robustness

Internal• Maintainability• Flexibility

• Portability• Reusability• Readability

• Testability• Understandability

This talk, we focus only on

Code Quality

Software Quality

External• Correctness• Usability• Efficiency• Reliability• Integrity• Adaptability• Accuracy• Robustness

Internal• Maintainability• Flexibility

• Portability• Reusability• Readability

• Testability• Understandability

Code Quality

Understandability Maintainability

Flexibility

PortabilityReusability

Readability

Testability

Code Quality

Flexibility

PortabilityReusability

Testability

Self-documenting

Self-documenting

Code QualityConstruction

Self-documenting

Code QualityConstruction

Self-documenting

Code QualityConstruction

Agenda

1. What is High Quality Code?

2. Variables (Good and Bad Examples)

3. Statements (Good and Bad Examples)

4. How to create High Quality Code?

VariablesGood and Bad Examples

Code Complete 2nd Part III Variables

Initializing Variables

Chapter 10

Initializing Variables

Chapter 10

Keep Variables “Live” for as Short a Time as Possible

Chapter 10

Group related statements

Chapter 10

Group related statements

Chapter 10

Use each variable for one purpose only

Chapter 10

Use each variable for one purpose only

Chapter 10

Considerations in Choosing Good Names

Chapter 11

Chapter 11

Naming Loop Indexes

Chapter 11

Naming Loop Indexes

Chapter 11

Naming Loop Indexes

Chapter 11

Naming Status Variables

Chapter 11Chapter 11

Naming Status Variables

Chapter 11

Naming Temporary Variables

Chapter 11

Naming Temporary Variables

Chapter 11

Kinds of Names to Avoid

• Avoid misleading names or abbreviations• e.g. FALSE, TRUE

• Avoid names with similar meanings• e.g. Input and inputValue;

recordNum and numRecords;fileNumber and fileIndex

• Avoid variables with different meanings but similar names

• Bad: clientRecs and clientReps• Better: clientRecords and clientReports

• Avoid names that sound similar, such as wrap and rap

Chapter 11

Kinds of Names to Avoid

Chapter 11

• Avoid numerals in names• Avoid file1 and file2, or total1 and total2

• Avoid misspelled words in names• Avoid misspelling highlight as hilite• Was it highlite? hilite? hilight? hilit? jai-a-lai-t? Who knows?

• Avoid words that are commonly misspelled in English• e.g. Absense, acummulate, acsend, calender, concieve,

defferred, definate, independance, occassionally

Kinds of Names to Avoid

Chapter 11

• Don’t differentiate variable names solely by capitalization• Names are unique• Avoid to use frd for fired,

FRD for final review duty, and Frd for full revenue disbursal.

• Avoid multiple natural languages• Avoid “color” or “colour” and “check” or “cheque”

• Avoid the names of standard types, variables, and routines

Kinds of Names to Avoid

Chapter 11

• Don’t use names that are totally unrelated to what the variables represent

• Bad: margaret and pookie. Who know?• Better: boyfriend, wife, and favoriteBeer are superior!

• Avoid names containing hard-to-read characters

Avoid “magic numbers”

Chapter 12

Avoid “magic numbers”

Chapter 12

Boolean Variables

Chapter 12

Boolean Variables

Chapter 12

Boolean Variables

Chapter 12

Boolean Variables

Chapter 12

Use enumerated types for readability

Chapter 12

Use enumerated types for readability

Chapter 12

Avoid literals, even “safe” ones

Chapter 12Chapter 12

Avoid literals, even “safe” ones

Chapter 12Chapter 12

Avoid literals, even “safe” ones

Chapter 12Chapter 12

Avoid literals, even “safe” ones

Chapter 12

Use structures to clarify data relationships

Chapter 12

Use structures to clarify data relationships

Chapter 12

Agenda

1. What is High Quality Code?

2. Variables (Good and Bad Examples)

3. Statements (Good and Bad Examples)

4. How to create High Quality Code?

StatementsGood and Bad Examples

Code Complete 2nd Part IV – Statements

Making Code Read from Top to Bottom

Chapter 12

Making Code Read from Top to Bottom

Chapter 12

Grouping Related Statements

Chapter 12

Chapter 15

Follow the if clause with a meaningful statement

Chapter 12

Chapter 15

Follow the if clause with a meaningful statement

Chapter 12

Chapter 15

Follow the if clause with a meaningful statement

Don’t make up phony variables to be able to use the case statement

Chapter 15

Don’t make up phony variables to be able to use the case statement

Chapter 15

In C++ and Java, avoid dropping through the end of a case statement

Chapter 15

Abnormal Loop-With-Exit Loops

Chapter 16

Don’t monkey with the loop index of a for loop to make the loop terminate

Chapter 16

Use meaningful variable names to make nested loops readable

Chapter 16

Use meaningful variable names to make nested loops readable

Chapter 16

Don’t use recursion for factorials or Fibonacci numbers

Chapter 17

Don’t use recursion for factorials or Fibonacci numbers

Chapter 17

Using true and false for Boolean Tests

Chapter 19

Using true and false for Boolean Tests

Chapter 19

Using true and false for Boolean Tests

Chapter 19

Agenda

1. What is High Quality Code?

2. Variables (Good and Bad Examples)

3. Statements (Good and Bad Examples)

4. How to create High Quality Code?

How to create High Quality Code?

Code Complete 2nd Part II – Creating High-Quality Code

Before we start…

Let’s talk about Software Construction first.

Construction Activities

Chapter 1

The book focus on these activities with highlight

Chapter 1

Construction is an…

Iterative process

Chapter 5

Design is …

• A Wicked Problem

• A Sloppy Process (Even If it Produces a Tidy Result)

• About Tradeoffs and Priorities

• A Heuristic Process

• And more…

Chapter 5

Form Consistent Abstractions

Chapter 5

Top-Down and Bottom-Up Design Approaches

Argument for Bottom Up

Argument for Top Down

Chapter 5

Top-Down and Bottom-Up Design Approaches

Argument for Bottom UpArgument for Top Down

No Argument, Really

Chapter 5

Software’s Primary Technical Imperative: Managing Complexity

Accidental and Essential Difficulties

Importance of Managing Complexity

Chapter 5

Hide Secrets (Information Hiding)

A good class interface is

like the tip of an iceberg,

leaving most of the class

unexposed.

Chapter 5

Hide Secrets (Information Hiding)

Hiding ComplexityHiding Sources

Value of Information Hiding

Chapter 5

• Asking “What does this class need to hide?”

If you can put a Function or Data into the class’s public interface without compromising its secrets, do. Otherwise, don’t.

Encapsulate Implementation Details

Chapter 5

Levels of Design

1.Software system

2.Subsystem/packages

3.Classes within packages

4.Data and routines within classes

5.Internal routine designChapter 5

Reasons to Create a Class

• Model real-world objects• Model abstract objects

• Reduce complexity• Isolate complexity• Hide implementation details

• Limit effects of changes• Hide global data

• Streamline parameter passing• Make central points of control

• Facilitate reusable code• Plan for a family of programs• Package related operations

• Accomplish a specific refactoring

Chapter 6

• Avoid creating god classes

• Eliminate irrelevant classes

• Avoid classes named after verbs

Classes to Avoid

Chapter 6

Class Foundations: Abstract Data Types (ADTs)

Picture from: Auto Transport Company ScamsChapter 6

If you need to change to a 12-point font size

Chapter 6

If you need to change to a 12-point font size

Chapter 6

Poor Abstraction

Chapter 6

Good Abstraction

Chapter 6

Better Abstraction

Chapter 6

Mixed Levels of Abstraction

Chapter 6

Consistent Levels of Abstraction

Chapter 6

Exposing Class’s Implementation Details

Chapter 6

Hiding Class’s Implementation Details

Chapter 6

What is the routines?

Chapter 6

What is the routines?

Chapter 6

Routines = Functions

Valid Reasons to Create a Routine

• Reduce complexity• Introduce an intermediate,

understandable abstraction

• Avoid duplicate code• Support subclassing• Hide sequences

• Hide pointer operations• Improve portability

• Simplify complicated Boolean tests

• Improve performance• To ensure all routines are

small?

Chapter 6

Operations That Seem Too Simple to Put Into Routines

Chapter 7Chapter 7

Operations That Seem Too Simple to Put Into Routines

Chapter 7Chapter 7

Operations That Seem Too Simple to Put Into Routines

Chapter 7Chapter 7

Operations That Seem Too Simple to Put Into Routines

Chapter 7

Good Routine Names

• Describe everything the routine does• Bad: ComputeReportTotals()

• Silly Names: ComputeReportTotalsAndOpenOutputFile()

• Avoid meaningless, vague, or wishy-washy verbs• Bad: HandleCalculation(), PerformServices(),OutputUser(), ProcessInput(),

and DealWithOutput()…

• HandleOutput() → FormatAndPrintOutput()

• Make names of routines as long as necessary

Chapter 7

Good Routine Names

• Don’t differentiate routine names solely by number

• Bad: Part1, Part2,

OutputUser0, OutputUser1, and OutputUser2

• To name a function, use a description of the return value

• e.g. cos(), customerId.Next(), printer.IsReady(), and pen.CurrentColor()

• To name a procedure, use a strong verb followed by an object

• e.g. PrintDocument(), CalcMonthlyRevenues(), CheckOrderlnfo(), and

RepaginateDocument()

Chapter 7

Good Routine Names

• Establish conventions for common operations

• e.g. employee.id.Get(), dependent.GetId(), supervisor(), candidate.id()

• Use opposites precisely

Chapter 7

How Long Can a Routine Be?

100

200Less then 200 lines is better.

Chapter 7

Don’t use routine parameters as working variables

Chapter 7

Don’t use routine parameters as working variables

Chapter 7

Limit the number of a routine’s parameters to about

Seven

7Chapter 7

What is Pseudocode?

Chapter 5

Pseudocode is an informal high-level descriptionof the operating principle of a computer programor other algorithm.

Pseudocode Principles

Chapter 5

Pseudocode Programming Process: Classes

Chapter 5

Pseudocode Programming Process: Routines

Chapter 5

Constructing Routines by Using the PPP

Chapter 5

Design the routine.

Code the routine.

Check the code.

Clean up loose ends.

Repeat as needed.

1

23

4

5

Code the Routine

Chapter 5

1

2

3

4

5

Write the routine declaration

Chapter 5

1

Writing the First and Last Statements Around Pseudocode

Chapter 5

2

Chapter 5

Turn the Pseudocode into High-level comments

Chapter 5Chapter 5

2

Chapter 5

The code for each comment has been filled in from here down.3

Chapter 15

Example of a Complete Routines Overview

Routine Header

Routine Interface

The code for each comment has been filled in from here down.

The last paragraph of Routine

Self-documenting

Code QualityConstruction

Thank You!

Q & A