Self-Expressive Code. A handbook of write readable code. Stephen Wang. This book is for sale at

Transcription

1

2 Self-Expressive Code A handbook of write readable code. Stephen Wang This book is for sale at This version was published on This is a Leanpub book. Leanpub empowers authors and publishers with the Lean Publishing process. Lean Publishing is the act of publishing an in-progress ebook using lightweight tools and many iterations to get reader feedback, pivot until you have the right book and build traction once you do Stephen Wang

3 Tweet This Book! Please help Stephen Wang by spreading the word about this book on Twitter! The suggested hashtag for this book is #Software Programming, Code Readability. Find out what other people are saying about the book by clicking on this link to search for this hashtag on Twitter: Programming, Code Readability

4 Contents Introduction Acknowledgement What Is Self-Expressive Code Part I Readability Chapter 1 Annoyance of Lower Readability Annoying Bugs Hard To Understand Hard To Change Or Extend Easy To Make Bugs In Hard To Refactor Further Reading

5 Introduction When we are writing programming code, readability issues happen. People often face some hard to read source codes. What kind of codes are lower readability? What caused this happen? How to solve these issues? All the above questions are big. Restricted by the programming language, codes can be written in predefined ways. People might think it is not possible to write source code as certain language. That s true. We could not write certain language, then let computer analyze the commands and run properly, but we can write source code as certain language as we can. Programming language provides some useful symbols allow programmers to write source code easy to understand. Some issues caused by English, some non-native speakers have smaller vocabulary set, they tend to use simple words only to express what they want to do. However, even for native speakers, they can give good names to classes, methods or variables, but when call these classes, methods, variables, problems also appear. That means, code readability is no only depend on the names, but also depend on how it will be called. Plus, the algorithm, the structure, the architecture will affect the readability of codes. Improve code s readability is not so easy. In this book, I would like to introduce a new way to write source code - Self-Expressive Code. As implied in its name, Self-Expressive Code means, the code itself can express what it will do. Programmers can understand the meaning of source code faster and easier. Self-Expressive Code is chasing for the way to write source code that could be understood at a glance. Java is still popular and influential. This book picked Java as its sample language.

6 Acknowledgement There is a list who helped editing this book. Michael Chen Liu Chengzhang Han Kuikui Thank my family, without their support, this book could not be published. The first edition of this book is published in Chinese on paper. The initial intention for this book is for help non-english speakers write more readable codes. Michael has reviewed the first edition and provided some useful suggestions. He also provided many useful ideas for the second edition. This is the second edition, chapters are re-organized, samples are revised. I hope this book can benefit programmers across the world, not only non-english speakers. This book referred the following books: Design Patterns:Elements of Reusable Object-Oriented Software¹, Erich Gamma, Richard Helm, Ralph Johnson, John Vlissides ISBN: Refactoring², Martin Folwer Clean Code³, Robert Martin The Art of Readable Code (Theory in Practice)⁴, Dustin Boswell, Trevor Foucher ¹ ² ³CleanCode:AHandbookofAgileSoftwareCraftsmanship ⁴

7 What Is Self-Expressive Code In assembly language, codes are written for machines, people can hard to read source code and guess its meaning. After decades, programming languages become more and more easy to read. Shortly, codes are written for people. However, in the real world, we could hard to read many codes in C# or Java, even certain words are used to name objects in programming. In a opened source famous platform, one module contains a bunch of lower readable codes. After read that code, it seems the authors of the codes tend to write source code for machines, not for people. We cannot know the real reason, but we could analyze the source code. The source code has: 1. if-else conditions that do not evaluate same object. 2. non-english names. 3. long branches/methods. 4. many duplications/similarities. Those above features show that the programmer were not pay enough attention about the reader s feeling. This third party company shared their source code on that famous platform for brand image or something. Unfortunately, the source code just leads to the opposite way. After read that code I started to worry about the quality of their health care products. Hope they have different process to make the products quality higher. So, what is good way to write readable source code? For instance, in a game application, player can control a hero to fight the enemy in a scene. The code could seem like: 1 scene.fight(hero, enemy, Kongfu.FIST); In the code above, readers cannot understand the fight direction between hero and enemy. An revised version could seem like: 1 hero.fight(enemy, Kongfu.FIST); For the restriction of programming language, constant should have its class name. The meaning of this code is clear, but the code still seems like to be a machine language, not human language. Then the ace version is appear:

8 What Is Self-Expressive Code 4 1 hero.fight(enemy).with("fist"); The fight() method returns a Fight object that has with() method. The with() method passed by a Kongfu name that allows a KongfuFactory to create a Kongfu object and calculate the damage. This process makes more classes, but it also make the source code more readable. Implement functionality is the basic responsibility of source code, but keep it readable, extensible, changeable are also important. As mentioned in the head of this section, codes are written for people. I suggest to write source code as certain language as possible. I named that method Self-Expressive Code. Before the word Self-Expressive Code appear in the world, there are two similar words: Self- Documenting Code⁵ and Self-Describing Code⁶ already existed. They might have the same meaning, but I think the word expressive is more expressive, so I named this way of writing code as Self- Expressive Code. ⁵ ⁶

9 Part I Readability Chapter 1 Annoyance of Lower Readability When programmers read others code, they would have feelings about the code. Just like users access a website. If website makes user unsatisfied, user will go away. If the code is not good for read, what would the reader do? The most frequently occurred thing might be spitting out dirty words. The worst thing is that after spit out, the reader noticed that the source were written by himself/herself. Apparently, lower readable codes make programmers unsatisfied. Lower readable codes may be a:

10 Part I Readability 6 1. Mouse Wheel Tester Long file, long method, long branch, those force readers to roll their mouse wheel continuously. The source code, in other side, is a mouse wheel tester. 2. Eye Tester Similar codes make user confused about the nuances. Similar codes force user to look inside with caution. 3. Memory Tester Name variables as a, b, c or count1, count2 to force readers remember meaning of these variables. 4. Patience Tester Long names hide the key information that forces user stop and think. Unformatted source make user to keep big patience to read. Deep nested source makes reader think the relationship harder. or, it may have such features: 1. Names Make No Sense Method names like : doprocess, invokemethod, executeservice. Variable names like : returnvalue, tempvalue, list, result. 2. Dialects Using other languages other than English, makes other readers totally have no idea about the names. Even they share the same language. YouYu in Chinese have at least eight possible meanings. ikou in Japanese have at least four possible meanings. 3. Made Up Words Using ambiguous words that misguide readers, such as float DBL. That leads readers to think DBL is the abbreviation of double. 4. Quiz Using complicated expressions to make things more complex. Lower readability also makes code hard to change, hard to extend, hard to fix bugs. Lower readability codes share one feature - forces readers stop and think, that causes lower productivity, lower quality.

11 Part I Readability Annoying Bugs Programmers are inevitable to face bugs. If it is easy to be fixed, programmers might not hate bugs too much. In the real world, however, bugs are hard to be reproduced, hard to be traced, hard to be fixed, or easy to degrade. Not reproducible One possible reason is that there are too many factors to make it happens again. And these factors are existing in the source code, but not in the business process. This reflects the code appended inner factors, and if possible, eliminate them to make bugs reproducible. Not traceable One possible reason is that the bug caused by one complicated line code. If user got an NullPointerException at the following code. Which is the root cause of the problem? 1 product.setupdater(user.getfullname()); Another possible reason is that the bug were produced by mis-use of third party framework. For example, Spring framework allows user to configure their xml to run system, but it is not easy to find if xml has mistake. Third possible reason is that the error message does not indicate the real reason. For example, Ebean allows user to access db easier. If the server name of Ebean is not set properly, User would get a message of NullPointerException. and user could not easily to solve this problem without reading the source code of Ebean. Not Fixable Degrade After tried so hard, programmer found the reason of the source code, but cannot fix that bug. Because it is a very influential place. If it changes, too much tests are required, but time is limited. After fixed the bug, it works. Unfortunately, another bug appears according to this fix. All those above annoyance occur frequently with lower readable codes.

12 Part I Readability Hard To Understand Negatives When a new programmer joined to a team, he/she needs to read source code before touch it. If the source code has lower readability, it takes long time to understand. Until the new programmer understood the source code, he/she could do nothing about fix bugs or apply changes. This also works for job transfer from a member to another. It depends on the readability, if the codes are easy to read, the time be taken is shorter, otherwise, longer time needed. There is a list that frequently happened in lower readable codes. Negative words contain a NOT information, if put negative variable into a conditional statement, it just like a quiz : not of not is positive. If it happens to be a non-adjective variable, the code becomes harder to read. 1 if ((hardkeyboardhidden == 1) == false) Circular Reference If object A contains an object B, and object B for some reasons needs reference from object A, the two objects have a circular reference, just like below: 1 class Container { 2 Context context; 3 Product product; 4 } 1 class Proudct { 2 //This is for calling of 'container.context' 3 Container container; 4 } In this case, container.product.container.product would be a strange object. In fact this is caused by wrong ownership. Diverse Meanings If a local variable in a method have diverse meanings, readers could not easily check the meaning of the variable at a line. The variable flag in the following code is hard to understand.

13 Part I Readability 9 1 public String registerlesson(long userid, long lessonid) { 2 int flag = 0; 3 4 flag = checkuserexist(userid); 5 6 if (flag == 0) { 7 return "User does not exist."; 8 } 9 10 flag = checklessonexist(lessonid); if (flag == 0) { 13 return "Lesson does not exist."; 14 } return ""; 17 } Diverse Branches Branches may have conditions, but the conditions should have same meaning, different values. If two connected branches have different conditions, it makes no sense. 1 public void method(int flag, String name) { 2 if (flag == 0) { 3 //process 1; 4 } else if (name.equals("abc")) { 5 //process 2; 6 } 7 } Ambiguous Names If the name of a method can not show its meaning, reader should read every and each line of its implementation to determine its real functionality. That takes time. The following is a sample of ambiguous name.

14 Part I Readability 10 1 public class Keyboard { 2 //Pressed the 'alt' key or alter to another keyboard layout? 3 public void alt() { 4 } 5 } Non-Match Documents Many maintenance engineers are confusing about that the source code have nor creditable documents, neither comments, which means the code is the only document. Unfortunately, most of these time, the source code is not readable too. 1.3 Hard To Change Or Extend Software changes. If a requirement change comes, how much time will be taken? The higher the changeability is, the shorter the time is needed. Changeability A widget⁷ place module in a system have magnet effects for widgets. That algorithm is changed frequently because widget have many sizes. But the code is hard to be changed, because the move method is too complicated: 1 private Widget[] widgets; 2 3 private int focus; 4 5 public void move(int dir) { 6 if (dir == 1) {// move right 7 if (widgets[focus].width == 1) { 8 int next = 0; 9 next = findnext(); 10 if (widgets[next].height == 2) { 11 if (widgets[next].y == widgets[focus].y) { 12 //omitted 13 } 14 //..omitted. 15 } else if (widgets[next].height == 3) { 16 if (widgets[next].y == widgets[focus].y) { ⁷

15 Part I Readability //omitted 18 } 19 //..omitted. 20 } 21 } 22 } else (dir == -1) { //move left 23 //omitted 24 } 25 } In this complicated algorithm, programmer try to enumerate every possibility about moving widget. Any new possibility will extend the method. The final version of source is very terrible, and messed up. Even a small change to this algorithm will cause big modification. Extensibility An input method system on android platform is required to have new input device : remote control and game pad. Below is the skeleton of the implemented codes: 1 public class Keyboard { 2 public boolean onkeydown(int keycode, KeyEvent event) { 3 if (hardkeyboardconnected == 0) { 4 //treat with soft keyboard 5 } else { 6 //treat with hard keyboard 7 if (keycode >= KeyEvent.KEYCODE_A 8 && keycode <= KeyEvent.KEYCODE_Z) { 9 } else if (keycode == KeyEvent.KEYCODE_ENTER) { 10 } else if (keycode == KeyEvent.KEYCODE_SPACE) { 11 } else if (keycode == KeyEvent.KEYCODE_SHIFT) { 12 } 13 } 14 } 15 } When add device like remote control and game pad, because it is not detectable for android system, like a physical keyboard plugged in. The code becomes:

16 Part I Readability 12 1 public class Keyboard { 2 public boolean onkeydown(int keycode, KeyEvent event) { 3 if (hardkeyboardconnected == 0) { 4 //treat with soft keyboard 5 } else { 6 //treat with hard keyboard 7 if (keycode >= KeyEvent.KEYCODE_A 8 && keycode <= KeyEvent.KEYCODE_Z) { 9 } else if (keycode == KeyEvent.KEYCODE_ENTER) { 10 } else if (keycode == KeyEvent.KEYCODE_SPACE) { 11 } else if (keycode == KeyEvent.KEYCODE_SHIFT) { 12 } else if (keycode >= KeyEvent.KEYCODE_BUTTON_1 13 && keycode <= KeyEvent.KEYCODE_BUTTON_10) { //for remote control 14 } else if (keycode >= KeyEvent.KEYCODE_BUTTON_A 15 && keycode <= KeyEvent.KEYCODE_BUTTON_C) { //for game pad 16 } else if (keycode >= KeyEvent.KEYCODE_BUTTON_X 17 && keycode <= KeyEvent.KEYCODE_BUTTON_Z) { //for game pad 18 } 19 } 20 } 21 } If follow this trend to modify source code, the source code will be very fatty and buggy. All of the above system has lower readability. 1.4 Easy To Make Bugs In. Not Match It may cause bug when call a one method that declared one behavior, but actually did two. 1 public void update() { 2 reloaddata(); 3 savefile(); 4 } Duplications/Similarities It may cause bug in case that should call method A, but called a similar method B.

17 Part I Readability 13 1 public void clear() { 2 //remove all elements 3 } 1 public void clean() { 2 //remove all dump data. 3 } Ambiguous It is confused when trying to call a method with ambiguous name and implementation. 1 public int[] countdifferentseries(int[][] baskettwodarray) { 2 int count = 0; 3 //omitted. 4 return differentseriescount; 5 } This method start with count, but returns an array. It is not easy to understand the meaning of this code in short. If want to count each item in the array, how about to calculate separately in a loop? Complicated Deeper nested codes makes code hard to read, hard to understand. 1 private Widget[] widgets; 2 3 private int focus; 4 5 public void move(int dir) { 6 if (dir == 1) {// move right 7 if (widgets[focus].width == 1) { 8 int next = 0; 9 next = findnext(); 10 if (widgets[next].height == 2) { 11 if (widgets[next].y == widgets[focus].y) { 12 //omitted

18 Part I Readability } 14 //..omitted. 15 } else if (widgets[next].height == 3) { 16 if (widgets[next].y == widgets[focus].y) { 17 //omitted 18 } 19 //..omitted. 20 } 21 } 22 } else (dir == -1) { //move left 23 //omitted 24 } 25 } When touch this code, it is very easy to make bugs in. 1.5 Hard To Refactor Inconsistent Style Many programmers do not care about the style of source code. In their editor both of below exist. 1 a=a+1; 1 a = a + 1; In this case, if reader want to search something, they do not know which pattern should they use. They have to add additional information into the search box - Make it regular expression. Also, the mixed style exist together makes new joined programmers confused - What rule should I follow if I want to change the source code. Inconsistent Words Not only the coding style, if the terms or words are not inconsistent in one system, readers will also be confused.

19 Part I Readability 15 In one file, save means insert, but in another file, save means update, so why not use insert and update to avoid this? Inconsistent Process Besides, in a system, treat similar objects in different ways may take extra time to understand the difference. In a input method system, typed alphabet will be transferred to certain characters according to the selected transfer rules. The following code shows the design simply. 1 public interface TransferEngine { 2 public List<String> transfer(); 3 } 1 public class InputMethodService { 2 public List<String> transfer() { 3 String text = gettypedalphabets(); 4 TransferEngine engine = getselectedtransferengine(); 5 List<String> candidates = engine.transfer(text); 6 return candidates; 7 } 8 } If added one rule, it should be a implementation of TransferEngine, 1 public class HiraganaEngine implements TransferEngine { 2 public List<String> transfer(string text) { 3 //... 4 } 5 } However, the author changed code as follows:

20 Part I Readability 16 1 public class InputMethodService { 2 3 public List<String> transfer() { 4 String text = gettypedalphabets(); 5 TransferEngine engine = getselectedtransferengine(); 6 7 List<String> candidates = null 8 9 if (engine instanceof SymbolEngine) { 10 candidates = new ArrayList<String>(); 11 candidates.add(text); 12 return candidates; 13 } candidates = engine.transfer(text); 16 return candidates; 17 } 18 }

21 Further Reading Chapter 2. What Makes Readability Lower 2.1 English Skills 2.2 Programming Language Grammar 2.3 Naming 2.4 Architecture 2.5 Structure 2.6 Comment 2.7 Style 2.8 Restrictive Rules Chapter 3. An Unreadable Experience 3.1 Usage Of Words 3.2 Style 3.3 Algorithm 3.4 Revise Part II Improvement Chapter 4. Use English Properly 4.1 Frequently Found Mistakes 4.2 Prefix, Suffix 4.3 Pair Words 4.4 Abbreviation 4.5 Word Class 4.6 Grammar 4.7 Tense 4.8 Negatives Chapter 5. Use Programming Language Features > 5.1 Annotation > 5.2 Exception > 5.3 Reflect > 5.4 Generic > 5.5 Lambda Expression Chapter 6. Naming Improvement 6.1 Package 6.2 Interface 6.3 Class 6.4 Enumeration 6.5 Annotation 6.6 Method 6.7 Variable 6.8 Constant 6.9 Similarities 6.10 Keywords 6.11 Other Improvements Chapter 7. Architectural Improvement 7.1 Task Split 7.2 Inner Classes, Interfaces and Enumerations 7.3 Anonymous Class 7.4 Relationship 7.5 Limited Values 7.6 Avoid Class Explosion 7.7 Abstraction 7.8 Responsibility Chapter 8. Structural Improvement

22 Further Reading Shorten Long Method 8.2 Reduce Parameter Count 8.3 Reduce Nested Depth 8.4 Eliminate Duplications/Similarities 8.5 Decouple 8.6 Reduce Influence of Multi-Factors 8.7 Avoid Class Cast 8.8 Shorten Long Conditions 8.9 Eliminate Useless Codes 8.10 Remove Temporary Variables Chapter 9. Commentary Improvement 9.1 Java Doc 9.2 FIXME, TODO, XXX 9.3 Copyright 9.4 Class Explanation 9.5 Method Comment 9.6 Process Comment 9.7 Comment Out Source Code Chapter 10. Stylistic Improvement 10.1 Indent 10.2 Alignment 10.3 Space 10.4 Code Region 10.5 Line Length and Tab 10.6 New Line 10.7 Braces, Brackets and Parentheses 10.8 Code Region Chapter 11. Scriptic Improvement 11.1 Object Oriented JavaScript 11.2 HTML 11.3 JSP 11.4 SQL 11.5 OS Script Chapter 12. Configurational Improvement 12.1 XML 12.2 JSON 12.3 Properties 12.4 Yaml 12.5 CSS Chapter 13. Symbolic Improvement 13.1 Period 13.2 Logical Operators 13.3 Computing Operators 13.4 Quotations 13.5 String Parameters Chapter 14. Algorithmic Improvement 14.1 Recursion 14.2 Replace List With Map 14.3 Replace Index With List 14.4 Apply Domain Specific Language 14.5 Apply Dynamic Design Patterns Chapter 15. Readability Of Test Code 15.1 Assertion 15.2 Test Case 15.3 Test Fixture 15.4 Stability Of Test Codes Chapter 16. Other Improvements

23 Further Reading URL Log 16.6 Part III Exploring Chapter 17. Code Generator 17.1 Problems Of Code Generator 17.2 Layout Editor 17.3 Dynamic Codes Chapter 18. Help From IDE 18.1 Auto-Formatter 18.2 Spell-Checker 18.3 Style-Checker 18.4 Auto-Complete Chapter 19. Code Review 19.1 Machine s Work 19.2 Quick Read

24 Further Reading S To Codes 19.4 Looks Good 19.5 Convention 19.6 Misunderstanding Chapter 20. Readability Improving of Legacy Code 20.1 Make Sure Test Code Exist 20.2 Apply Tools 20.3 Small Improvement 20.4 Entire Improvement 20.5 Rewrite Chapter 21. Evolutionary Design 21.1 Keep Readability From Line Keep Clean 21.3 Just Enough 21.4 Think How It Would Be Called 21.5 Use Third Party Libraries 21.6 Be Habit 21.7 Time To Test Chapter 22. A Journey To Improving Readability 22.1 Create Android IME Service 22.2 Layout 22.3 Input Device 22.4 Process Button(Input) 22.5 Process Button(Operation) 22.6 Control Input(Touch Screen)