Give a talk about Code Quality.

1. 高品質軟體的基本動作 -如何寫"好的" 程式
Guidelines in How to Create High Quality Code
Johnson J. Su
自由軟體鑄造場蘇展
2014/11/20
Code Complete 101

2. Johnson J. Su
Linkedin：https://www.linkedin.com/in/jansu
E-mail：johnsonsu@iis.sinica.edu.tw
TEL：(02) 2788-3799 ext. 1478

3. In This Talk
•
We will discuss
•
How to use Code Complete
•
What is high codequality
•
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

4. 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?

5. Before we start…

6. 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?

7. Have you ever thought…?
•
看不懂別人的Code在做什麼?
•
為什麼別人寫的Code 很凌亂?
•
如何寫出“品質好”,“可讀性高” 的Code?
•
Or more…?

8. Here’s your answer.

9. GuidanceCode Complete 2nd
If you are…
•
Junior Developer
•
Chapter 11, 18
•
Senior Developer
•
Chapter 4~9
•
Project Manager
•
Chapter 2, 33
•
Standard Maker
•
Chapter 32

10. GuidanceCode Complete 2nd
If you are…
•
Junior Developer
•
Chapter 11, 18
•
Senior Developer
•
Chapter 4~9
•
Project Manager
•
Chapter 2, 33
•
Standard Maker
•
Chapter 32

11. 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?

12. What is High Quality Code?

13. Software Quality?

14. Software Quality
External
•
Correctness
•
Usability
•
Efficiency
•
Reliability
•
Integrity
•
Adaptability
•
Accuracy
•
Robustness
Internal
•
Maintainability
•
Flexibility
•
Portability
•
Reusability
•
Readability
•
Testability
•
Understandability

15. This talk, we focus onlyonCode Quality

16. Software Quality
External
•
Correctness
•
Usability
•
Efficiency
•
Reliability
•
Integrity
•
Adaptability
•
Accuracy
•
Robustness
Internal
•
Maintainability
•
Flexibility
•
Portability
•
Reusability
•
Readability
•
Testability
•
Understandability

17. Code Quality
Understandability
Maintainability
Flexibility
Portability
Reusability
Readability
Testability

18. Code Quality
Flexibility
Portability
Reusability
Testability
Self-documenting

19. Self-documenting
Code Quality
Construction

20. Self-documenting
Code Quality
Construction

21. Self-documenting
Code Quality
Construction

22. 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?

23. Variables
Good and Bad Examples
Code Complete 2ndPart III Variables

24. Initializing Variables
Chapter 10

25. Initializing Variables
Chapter 10

26. Keep Variables “Live” for as Short a Time as Possible
Chapter 10

27. Group related statements
Chapter 10

28. Group related statements
Chapter 10

29. Use each variable for one purpose only
Chapter 10

30. Use each variable for one purpose only
Chapter 10

31. Considerations in Choosing Good Names
Chapter 11

32. Chapter 11

33. Naming Loop Indexes
Chapter 11

34. Naming Loop Indexes
Chapter 11

35. Naming Loop Indexes
Chapter 11

36. Naming Status Variables
Chapter 11
Chapter 11

37. Naming Status Variables
Chapter 11

38. Naming Temporary Variables
Chapter 11

39. Naming Temporary Variables
Chapter 11

40. Kinds of Names to Avoid
•
Avoid misleading names or abbreviations
•
e.g. FALSE, TRUE
•
Avoid names with similar meanings
•
e.g. Inputand inputValue; recordNumand numRecords; fileNumberand fileIndex
•
Avoid variables with different meanings but similar names
•
Bad: clientRecsand clientReps
•
Better: clientRecordsand clientReports
•
Avoid names that sound similar, such as wrap and rap
Chapter 11

41. Kinds of Names to Avoid
Chapter 11
•
Avoid numerals in names
•
Avoid file1and file2, or total1and total2
•
Avoid misspelled words in names
•
Avoid misspelling highlightas hilite
•
Was it highlite? hilite? hilight? hilit? jai-a-lai-t? Whoknows?
•
Avoid words that are commonly misspelled in English
•
e.g. Absense, acummulate, acsend, calender, concieve, defferred, definate, independance, occassionally

42. Kinds of Names to Avoid
Chapter 11
•
Don’t differentiate variable names solely by capitalization
•
Names are unique
•
Avoid to use frdfor fired, FRDfor finalreviewduty, and Frdfor full revenue disbursal.
•
Avoid multiple natural languages
•
Avoid “color” or “colour” and “check” or “cheque”
•
Avoid the names of standard types, variables, and routines

43. Kinds of Names to Avoid
Chapter 11
•
Don’t use names that are totally unrelated to what the variables represent
•
Bad: margaretand pookie. Who know?
•
Better: boyfriend, wife, and favoriteBeerare superior!
•
Avoid names containing hard-to-read characters

44. Avoid “magic numbers”
Chapter 12

45. Avoid “magic numbers”
Chapter 12

46. Boolean Variables
Chapter 12

47. Boolean Variables
Chapter 12

48. Boolean Variables
Chapter 12

49. Boolean Variables
Chapter 12

50. Use enumerated types for readability
Chapter 12

51. Use enumerated types for readability
Chapter 12

52. Avoid literals, even “safe” ones
Chapter 12
Chapter 12

53. Avoid literals, even “safe” ones
Chapter 12
Chapter 12

54. Avoid literals, even “safe” ones
Chapter 12
Chapter 12

55. Avoid literals, even “safe” ones
Chapter 12

56. Use structures to clarify data relationships
Chapter 12

57. Use structures to clarify data relationships
Chapter 12

58. 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?

59. Statements
Good and Bad Examples
Code Complete 2ndPart IV –Statements

60. Making Code Read from Top to Bottom
Chapter 12

61. Making Code Read from Top to Bottom
Chapter 12

62. Grouping Related Statements
Chapter 12

63. Chapter 15
Follow the if clause with a meaningful statement
Chapter 12

64. Chapter 15
Follow the if clause with a meaningful statement
Chapter 12

65. Chapter 15
Follow the if clause with a meaningful statement

66. Don’t make up phony variables to be able to use the case statement
Chapter 15

67. Don’t make up phony variables to be able to use the case statement
Chapter 15

68. In C++ and Java, avoid dropping through the end of a case statement
Chapter 15

69. Abnormal Loop-With-Exit Loops
Chapter 16

70. Don’t monkey with the loop index of a for loop to make the loop terminate
Chapter 16

71. Use meaningful variable names to make nested loops readable
Chapter 16

72. Use meaningful variable names to make nested loops readable
Chapter 16

73. Don’t use recursion for factorials or Fibonacci numbers
Chapter 17

74. Don’t use recursion for factorials or Fibonacci numbers
Chapter 17

75. Using true and false for Boolean Tests
Chapter 19

76. Using true and false for Boolean Tests
Chapter 19

77. Using true and false for Boolean Tests
Chapter 19

78. 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?

79. How to create High Quality Code?
Code Complete 2ndPart II –Creating High-Quality Code

80. Before we start…
Let’s talk about Software Constructionfirst.

81. Construction Activities
Chapter 1

82. The book focus on these activities with highlight
Chapter 1

83. Construction is an…
Iterative
process
Chapter 5

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

85. Form Consistent Abstractions
Chapter 5

86. Top-Down and Bottom-Up Design Approaches
Argument for Bottom Up
Argument for Top Down
Chapter 5

87. Top-Down and Bottom-Up Design Approaches
Argument for Bottom Up
Argument for Top Down
No Argument, Really
Chapter 5

88. Software’s Primary Technical Imperative: Managing Complexity
Accidental and Essential Difficulties
Importance of Managing Complexity
Chapter 5

89. Hide Secrets (Information Hiding)
Agoodclassinterfaceislikethetipofaniceberg, leavingmostoftheclassunexposed.
Chapter 5

90. Hide Secrets (Information Hiding)
Hiding Complexity
Hiding Sources

91. Value of Information Hiding
Chapter 5
•
Asking “What does this class need to hide?”
If you can put a Functionor Datainto the class’s public interfacewithout compromising its secrets, do. Otherwise, don’t.

92. Encapsulate Implementation Details
Chapter 5

93. Levels of Design
1.Software system
2.Subsystem/packages
3.Classes within packages
4.Data and routines within classes
5.Internal routine design
Chapter 5

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

95. •
Avoid creating god classes
•
Eliminate irrelevant classes
•
Avoid classes named after verbs
Classes to Avoid
Chapter 6

96. Class Foundations: Abstract Data Types (ADTs)
Picture from: Auto Transport Company Scams
Chapter 6

97. If you need to change to a 12-point font size
Chapter 6

98. If you need to change to a 12-point font size
Chapter 6

99. Poor Abstraction
Chapter 6

100. Good Abstraction
Chapter 6

101. Better Abstraction
Chapter 6

102. Mixed Levels of Abstraction
Chapter 6

103. Consistent Levels of Abstraction
Chapter 6

104. Exposing Class’s Implementation Details
Chapter 6

105. Hiding Class’s Implementation Details
Chapter 6

106. What is the routines?
Chapter 6

107. What is the routines?
Chapter 6
Routines = Functions

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

109. Operations That Seem Too Simple to Put Into Routines
Chapter 7
Chapter 7

110. Operations That Seem Too Simple to Put Into Routines
Chapter 7
Chapter 7

111. Operations That Seem Too Simple to Put Into Routines
Chapter 7
Chapter 7

112. Operations That Seem Too Simple to Put Into Routines
Chapter 7

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

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

115. Good Routine Names
•
Establish conventions for common operations
•
e.g. employee.id.Get(), dependent.GetId(), supervisor(), candidate.id()
•
Use opposites precisely
Chapter 7

116. How Long Can a Routine Be?
100
200
Less then 200 lines is better.
Chapter 7

117. Don’t use routine parameters as working variables
Chapter 7

118. Don’t use routine parameters as working variables
Chapter 7

119. Limit the number of a routine’s parameters to about Seven7
Chapter 7

120. What is Pseudocode?
Chapter 5
Pseudocodeisaninformalhigh-leveldescriptionoftheoperatingprincipleofacomputerprogramorotheralgorithm.

121. PseudocodePrinciples
Chapter 5

122. PseudocodeProgramming Process: Classes
Chapter 5

123. PseudocodeProgramming Process: Routines
Chapter 5

124. 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
2
3
4
5

125. Code the Routine
Chapter 5
1
2
3
4
5

126. Write the routine declaration
Chapter 5
1

127. Writing the First and Last Statements Around Pseudocode
Chapter 5
2
Chapter 5

128. Turn the Pseudocodeinto High-level comments
Chapter 5
Chapter 5
2

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

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

131. Self-documenting
Code Quality
Construction

132. Thank You!

133. Q & A