Code readability: Session 2 (ver. 2, En)

Slide 1

Slide 1 text

codeReadabilitySession2 N_A_M_I_N_G

Slide 2

Slide 2 text

Brushup: Introduction and Principles Readability is for sustainable development The boy scout rule: Make code readable before changing it YAGNI: Implement only when required KISS: Choose a simple solution, beautiful != readable Single responsibility principle: Clarity the scope Premature optimization: Proﬁle/estimate before optimization

Slide 3

Slide 3 text

Contents of this lecture - Introduction and Principles - Natural language: Naming, Comments - Inner type structure: State, Function - Inter type structure: Dependency I, Dependency II - Follow-up: Review Naming > Introduction

Slide 4

Slide 4 text

What we name - Class, interface, enum, struct, protocol, trait - Variable, property, ﬁeld, parameter, constant value - Function, method, procedure, subroutine - Scope, package, module, namespace - Resource, ﬁle, directory, ID - etc. Naming > Introduction

Slide 5

Slide 5 text

What constitutes a good name Accurate - isVisible should not be used for sound Descriptive - width/height rather than w/h - imageView/imageBitmap/imageUrl rather than image Naming > Introduction

Slide 6

Slide 6 text

How to create a good name - Use correct grammar - Describe what rather than who/when - Choose words with narrow meanings - Avoid confusing abbreviations - Add words to explain type/unit - Use positive afﬁrmation Naming > Introduction

Slide 7

Slide 7 text

Topics - Use correct grammar - Describe what rather than who/when - Choose words with narrow meanings - Avoid confusing abbreviations - Add words to explain type/unit - Use positive afﬁrmation Naming > Use correct grammar

Slide 8

Slide 8 text

Why grammar is important Question 1: What is CallbackEventMessageClickViewText ? Answer 1?: A text of a click view (?) of a callback event message?? Question 2: What is MessageTextViewClickEventCallback ? Answer 2: A callback of click events on a message text view Naming > Use correct grammar

Slide 9

Slide 9 text

Use correct grammar "Grammar" depends on language and convention Let us look at the case of Java/Kotlin Naming > Use correct grammar

Slide 10

Slide 10 text

Types of names 1/2 - Noun: class, variable (including property function) imageView, HashSet, indexOf - Imperative: function findMessage, compareTo Naming > Use correct grammar

Slide 11

Slide 11 text

Types of names 2/2 - Adjective, participle: interface, state type/constant Iterable , PLAYING , CONNECTED - Interrogative, third-person verb: boolean value/function isTextVisible , contains , equalsTo , may / shouldShow - Adverb phrase with preposition: converter, callback toInt , fromMemberId , onClickEvent Naming > Use correct grammar

Slide 12

Slide 12 text

Grammar: Noun Place the essential word at the end (= the word telling what it is/does) ! : MessageEventHandler , buttonHeight ! : xyzHeightForPortrait (do not use for a class name) ! : HandlerMessageEvent (if it is a handler), heightPortrait Exception: Property function with a preposition e.g., indexOf(value) , maxValueIn(array) Naming > Use correct grammar

Slide 13

Slide 13 text

Grammar: Imperative Place a verb at ﬁrst "get X": ! getX, " xGet "post Y": ! postY, " yPost "map to Z": ! mapToZ, " toZMap, zToMap Naming > Use correct grammar

Slide 14

Slide 14 text

How a name in a wrong order is created class UserActionEvent class UserActionEventSwipe: UserActionEvent() class UserActionEventClickMessageText: UserActionEvent() class UserActionEventClickProfileImage: UserActionEvent() mutableListOf() How the code looks on the caller side is important Do not focus only on superﬁcial consistency Naming > Use correct grammar

Slide 15

Slide 15 text

Grammar: Summary Types for a name Noun, imperative, adjective, interrogative (+ third person), adverb Word order is important Check how the name looks on the caller side Naming > Use correct grammar

Slide 16

Slide 16 text

Slide 17

Slide 17 text

Describe "what" rather than "who/when" A name must answer ! What a class/variable is ! What a function does A name should not mention to the caller ! Who it calls/uses ! When/Where/Why/How it's called/used Naming > Describe what rather than who/when

Slide 18

Slide 18 text

Function name example: Declaration side ! Describe what this function does class MessageRepository { fun storeReceivedMessage(data: MessageData) { ! Describe when this function should be called class MessageRepository { fun onMessageReceived(data: MessageData) { Naming > Describe what rather than who/when

Slide 19

Slide 19 text

Function name example: Caller side ! We can know what happens by the calling code repository.storeReceivedMessage(messageData) presenter.showNewReceivedMessage(messageData) ! We are unable to know what happens repository.onMessageReceived(messageData) presenter.onMessageReceived(messageData) Naming > Describe what rather than who/when

Slide 20

Slide 20 text

Function name example: Another bad reason The function responsibility is ambiguous class MessageViewPresenter { fun onMessageReceived(data: MessageData) { // View presentation code for new message ... repository.onMessageReceived(data) // !! May cause a duplicate call bug repository.onMessageReceived(messageData) presenter.onMessageReceived(messageData) Naming > Describe what rather than who/when

Slide 21

Slide 21 text

Parameter name example: Declaration side ! We can know what happens if it is true fun showHistory(shouldShowDialogOnError: Boolean) ! We cannot know what happens if it is true fun showHistory(isCalledAtMainScreen: Boolean) Naming > Describe what rather than who/when

Slide 22

Slide 22 text

Parameter name example: Drawbacks of "who" 1: The name easily becomes obsolete // ... from another screen requiring dialog showHistory(isCalledAtMainScreen = true) 2: The parameter will be used for other purposes if (isCalledAtMainScreen) { setScreenTitle("Main") ... Would causes a bug if 1 and 2 happen at the same time Naming > Describe what rather than who/when

Slide 23

Slide 23 text

Describe what: Exception May need to name by "how/when" for an abstract callback - e.g., onClicked, onSwiped, onDestroyedɹ - Because "what" is not decided on the declaration We should name by "what" if possible even for a callback abstract fun toggleSelectionState() ... view.setClickCallback { toggleSelectionState() } Naming > Describe what rather than who/when

Slide 24

Slide 24 text

Describe what: Summary Describe "what" it is/does = Should not mention to the caller (who/when/where/why/how) - Show code responsibility clearly - Make caller code readable Exception: Interface with no deﬁnition of "what" it does Naming > Describe what rather than who/when

Slide 25

Slide 25 text

Slide 26

Slide 26 text

Ambiguous words: Example 1/2 Question: What does initializationFlag represent? - shouldInitialize - isInitializing - is/wasInitialized - isInitializable - isNotInitialized (!!) Choose one from the above options (except for the last one) Naming > Choose words with narrow meanings

Slide 27

Slide 27 text

Ambiguous words: Example 2/2 Question: What does sizeLimit represent? - max, min? - height, width, byte, characters, length? Name maxHeight , for example. Naming > Choose words with narrow meanings

Slide 28

Slide 28 text

Rewording options to consider - ﬂag: is, was, should, can, may, will ... - check: is, query, verify, measure, filter, notify, update ... - good, ﬁne: valid, completed, reliable, secure, satisfactory ... - old: previous, stored, expired, invalidated, deprecated ... - tmp, retval: actual name Use a dictionary or a thesaurus Naming > Choose words with narrow meanings

Slide 29

Slide 29 text

Choose words with narrow meanings: Summary - Replace ambiguous words like flag or check - Use a dictionary or a thesaurus Naming > Choose words with narrow meanings

Slide 30

Slide 30 text

Slide 31

Slide 31 text

Abbreviations: Example 1/2 Question: What does im stand for? input method, illegal message, instance manager ... Do not create your own abbreviations - Recognizing is easier than recalling3 3 100 Things: Every Designer Needs to Know About People, Susan Weinschenk, 2011 Naming > Avoid confusing abbreviations

Slide 32

Slide 32 text

Abbreviations: Example 2/2 Question: What does str stand for? string, structure, stream, streak, street, sorted transaction record Abbreviations may be acceptable if commonly used - Abbreviations like URL and TCP are totally ﬁne - str for string is acceptable especially for a limited scope Naming > Avoid confusing abbreviations

Slide 33

Slide 33 text

Product-speciﬁc abbreviation Some abbreviations are used product-wide Make them readable for a new team member - Write documentation for class, variable, or function - Prepare glossary Naming > Avoid confusing abbreviations

Slide 34

Slide 34 text

Avoid confusing abbreviations: Summary - Your own abbreviations: Do not use them - Commonly used abbreviations: Acceptable for several cases - Product-speciﬁc abbreviations: Prepare document or glossary Naming > Avoid confusing abbreviations

Slide 35

Slide 35 text

Slide 36

Slide 36 text

Add words to explain type/unit Units and entities can be ambiguous in an integer type - timeout: timeoutInMillis, timeoutInSeconds - width: widthInPixels, widthInPoints, widthInInches - color: argbColorInt, colorResId - i, j, k: userIndex, row, col Naming > Add words to explain type/unit

Slide 37

Slide 37 text

Add words to explain type/unit: Aside Consider creating a wrapper class of a unit class Inch(val value: Int) class Centimeter(val value: Int) fun setWidth(width: Inch) = ... setWidth(Centimeter(10)) // Compile error! - "value class" (Scala) or "inline class" (Kotlin) may help you - Consider encapsulating units in a class (e.g., Kotlin's Duration) Naming > Add words to explain type/unit

Slide 38

Slide 38 text

Slide 39

Slide 39 text

Use positive afﬁrmation ! : Positive words, isEnabled ! : Negative words, isDisabled ! : Positive word with "not," "no," or "non," isNotEnabled ! : Negative word with "not," "no," or "non," isNotDisabled We can rename isNotDisabled → isEnabled, and isNotEnabled → isDisabled without any logic change Naming > Use positive afﬁrmation

Slide 40

Slide 40 text

Slide 41

Slide 41 text

Topics: One more thing Adhere to language/platform/product conventions Naming > Adhere to language/platform/product conventions

Slide 42

Slide 42 text

Language/platform/product conventions Adhere to convention/rule/manner of language/platform/project - Grammar: itemCount vs. numItem - Abbreviations: milliSeconds vs. millis vs. ms Refer to the standard libraries and APIs Create coding conventions of the product for ambiguous points Naming > Adhere to language/platform/product conventions

Slide 43

Slide 43 text

Summary Use accurate and descriptive names - What to describe: "what" rather than "who/when" - Grammar: word order - Word selection: narrow meaning, non-abbreviated, afﬁrmative Naming > Summary