Embed Size (px)
Citation preview
⾼高品質軟體的基本動作- 如何寫 "好的" 程式
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：[email protected]
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
