高品質軟體的基本動作 101 + 102 for NUU

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

Guidelines in How to Create High Quality Code

bookjan

⾃自由軟體鑄造場 蘇展2015/04/15

Code Complete 101 + 102

bookjan

Linkedin：https://www.linkedin.com/in/bookjan E-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

• Basic concepts of Software Construction

• We will not discuss

• 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. Self-Documenting code

5. 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 more readable and

High quality code?

• and more…?

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

THE

REFEERENCE

BOOK

Guidance Code Complete 2nd

THE

REFEERENCE

BOOK

• Complete software-construction reference • Ready-to-use checklists • Larger perspective on software development • Absence of hype • Concepts applicable to most common language • Numerous code examples • Access to other sources of information

THE

REFEERENCE

BOOK

Key Benefits of This Handbook

Agenda

1. What is High Quality Code?

2. Variables (Good and Bad Examples)

3. Statements (Good and Bad Examples)

4. Self-Documenting Code

5. How to create High Quality Code?

6. Tips to improve Code Quality

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 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. Self-Documenting Code

5. How to create High Quality Code?

VariablesGood and Bad Examples

Code Complete 2nd Part III Variables

VariablesGood and Bad Examples

Code Complete 2nd Part III Variables

Good Bad

Making Variable Declarations Easy

• Turn off implicit declarations

• Declare all variables

• Use naming conventions

• Check variable names

Chapter 10

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. Self-Documenting Code

5. How to create High Quality Code?

StatementsGood and Bad Examples

Code Complete 2nd Part IV – Statements

Good Bad

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

73

In C++, clearly and unmistakably identify flow-throughs at the end of a case statement

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. Self-Documenting Code

5. How to create High Quality Code?

Self-Documenting CodeGood and Bad Examples

Code Complete 2nd Part VII

Good Bad

Programming Style as Documentation

Chapter 32

Programming Style as Documentation

Chapter 32

Commenting Style - Hard to Maintain

Chapter 32

Commenting Style - Easy to Maintain

Chapter 32

Endline Comment

Chapter 32

Endline Comment

Chapter 32

Good Comment & Good Code

Chapter 32

Good Comment & Good Code

Chapter 32

Don’t comment tricky code, rewrite it

Chapter 32

Commenting Routines

Chapter 32

Commenting Routines - input and output

Chapter 32

Agenda

1. What is High Quality Code?

2. Variables (Good and Bad Examples)

3. Statements (Good and Bad Examples)

4. Self-Documenting Code

5. 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.

What Is Software Construction?

http://www.newhealthguide.org/images/10421225/mental%20retardation.jpg

Software Construction Activities

100

This book focuses on…

101

Specific Tasks in Construction• Verifying that the groundwork has been laid so

that construction can proceed successfully

102

Specific Tasks in Construction• Verifying that the groundwork has been laid so

that construction can proceed successfully • Determining how your code will be tested

103

Specific Tasks in Construction• Verifying that the groundwork has been laid so

that construction can proceed successfully • Determining how your code will be tested • Designing and writing classes and routines

104

Specific Tasks in Construction• Verifying that the groundwork has been laid so

that construction can proceed successfully • Determining how your code will be tested • Designing and writing classes and routines • Creating and naming variables and named

constants

105

Specific Tasks in Construction• Verifying that the groundwork has been laid so

that construction can proceed successfully • Determining how your code will be tested • Designing and writing classes and routines • Creating and naming variables and named

constants • Selecting control structures and organizing

blocks of statements

106

Specific Tasks in Construction• Verifying that the groundwork has been laid so

that construction can proceed successfully • Determining how your code will be tested • Designing and writing classes and routines • Creating and naming variables and named

constants • Selecting control structures and organizing

blocks of statements • Unit testing, integration testing, and

debugging your own code 107

Specific Tasks in Construction• Reviewing other team members’ low-level

designs and code and having them review yours

108

Specific Tasks in Construction• Reviewing other team members’ low-level

designs and code and having them review yours

• Polishing code by carefully formatting and commenting it

109

Specific Tasks in Construction• Reviewing other team members’ low-level

designs and code and having them review yours

• Polishing code by carefully formatting and commenting it

• Integrating software components that were created separately

110

Specific Tasks in Construction• Reviewing other team members’ low-level

designs and code and having them review yours

• Polishing code by carefully formatting and commenting it

• Integrating software components that were created separately

• Tuning code to make it faster and use fewer resources

111

Why Software Construction

Is So Important?

Here’s Why• Construction is a large part of software

development

113

Here’s Why• Construction is a large part of software

development • Construction is the central activity in software

development

114

Here’s Why• Construction is a large part of software

development • Construction is the central activity in software

development • With a focus on construction, the individual

programmer’s productivity can improve enormously

115

Here’s Why• Construction is a large part of software

development • Construction is the central activity in software

development • With a focus on construction, the individual

programmer’s productivity can improve enormously

• Construction’s product, the source code, is often the only accurate description of the software

116

Here’s Why• Construction is a large part of software

development • Construction is the central activity in software

development • With a focus on construction, the individual

programmer’s productivity can improve enormously

• Construction’s product, the source code, is often the only accurate description of the software

• Construction is the only activity that’s guaranteed to be done

117

OK! I got it…

Should I need to care about before the construction?

Most Important of All - Problem Definition

119

Wrong Problem Definition

120

Right Problem Without Good Requirements

121

Right Problem Without Good Software Architecture

122

123

DVCS(Distributed Version Control System )

Made by Linus Torvalds for Linux

He spent about 10 DAYS to commit kernel code using git…

He said that it all depended on getting the basic ideas right…

I'd seen the problems others had, and I wanted to avoid doing.

http://www.linux.com/news/featured-blogs/185-jennifer-cloer/821541-10-years-of-git-an-interview-with-git-creator-linus-torvalds

One more thing…

Construction is an…

Iterative process

Chapter 5

126

https://www.flickr.com/photos/j_sherman/6128691125/

Design Mental Picture

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

Desirable Characteristics of a Design

• Minimal complexity

• Ease of maintenance

• Loose coupling • Extensibility

• Reusability

• High fan-in

• Low-to-medium fan-out

• Portability

• Leanness

• Stratification

• Standard techniques

Chapter 5

Form Consistent Abstractions

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 Design1.Software system

2.Subsystem/packages

3.Classes within packages

4.Data and routines within

classes

5.Internal routine design

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

Design also is an…

Iterative process

Chapter 5

How to create High Quality Code?

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

Let’s beginning~

140

Packages & Classes & Functions

Package

Class

add() contains() equals() getBounds2d() … getSize() isEmpty() …

Functions

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

Class Foundations: Abstract Data Types (ADTs)

Picture from: Auto Transport Company ScamsChapter 6

Example of the Need for an ADT

Chapter 6

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

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

Chapter 6

Benefits of Using ADT

• Avoid creating god classes

• Eliminate irrelevant classes

• Avoid classes named after verbs

Classes to Avoid

Chapter 6

Class Interface - Poor Abstraction

Chapter 6

Class Interface - Good Abstraction

Chapter 6

Class Interface - Better Abstraction

Chapter 6

Class Interface - Mixed Levels of Abstraction

Chapter 6

Class Interface - 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

• 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

Chapter 7

7

What is Pseudocode?

Chapter 5

Pseudocode is an informal high-level description of the operating principle of a computer program or 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

本簡報授權聲明

除另有聲明外，本簡報內容採⽤用 Creative Commons「姓名標⽰示 - ⾮非商業性」台灣 3.0 版授權條款。 歡迎⾮非商業⺫⽬目的的重製、散布或修改本簡報的內容，但請標明：(1)原作者姓名；(2)本簡報標題；(3)演講⽇日期。 簡報中所取⽤用的圖形創作乃截取⾃自網際網路，僅供演講者於⾃自由軟體推廣演講時主張合理使⽤用，請讀者不得對其再⾏行取⽤用，除⾮非您本⾝身⾃自忖亦符合主張合理使⽤用之情狀，且⾃自負相關法律責任。

THANK YOU Website: www.openfoundry.org Phone: 02-2788-3799 ext. 1478