Readable code - Available without Prescription

Slide 1

Slide 1 text

Daniel van Berzon @ocastahq ocasta.com @dvberzon vanberzon.com Readable code (Available without prescription)

Slide 2

Slide 2 text

Grammar

Slide 3

Slide 3 text

“Rachel and me went to the cinema” “Rachel and I went to the cinema” A B C

Slide 4

Slide 4 text

Readable Code

Slide 5

Slide 5 text

A B C const sorted = input .split('') .sort() .join(''); const chars = input.split(''); const sortedChars = chars.sort(); const sorted = sortedChars.join('')

Slide 6

Slide 6 text

Grammar Readable Code Spanish Dutch Politics Photography Magic Singing Guilbert & Sullivan FC Barcelona Cheese Flamenco Film Popular Science

Slide 7

Slide 7 text

Grammar Readable Code

Slide 8

Slide 8 text

.com

Slide 9

Slide 9 text

Readable Code

Slide 10

Slide 10 text

Writing code On your own For the computer Student

Slide 11

Slide 11 text

Reading code Collaborating For developers Professional Reading : Writing 10 : 1 - Robert C Martin

Slide 12

Slide 12 text

Student Professional Cool Clever Efficient Succinct Exciting Clear Simple Intuitive Structured Boring write_code => => read_code

Slide 13

Slide 13 text

const = 0; • Too many options • Spoilers • Other people … is hard to write Code that is easy to read z

Slide 14

Slide 14 text

const postcodeValid = (params) => { return strPresent(params.postcode); } const validateParams = (params) => { return firstNameValid(params) && lastNameValid(params) && emailValid(params) && postcodeValid(params); } Whitespace Indentation Break up long lines Legible Code ≠ Readable Code Easier on the eye?

Slide 15

Slide 15 text

Readability Structure Consistency Brevity Convention Syntax Naming Clarity Approach

Slide 16

Slide 16 text

Rules? Structure Consistency Brevity Convention Syntax Naming Clarity Approach

Slide 17

Slide 17 text

Grammar

Slide 18

Slide 18 text

Grumpy English Teacher

Slide 19

Slide 19 text

"Never end a sentence with a preposition!"

Slide 20

Slide 20 text

What is he on about? preposition About what is he on? On about what is he? !

Slide 21

Slide 21 text

“Rachel and me went to the cinema” “Rachel and I went to the cinema” A B C

Slide 22

Slide 22 text

B: Rachel and I went to the cinema 2 pronouns for referring to oneself “I” as subject: “I went to the cinema” “Me” as object: "Rachel noticed me” “Rachel” and “I” are both subjects “Rachel and I went to the cinema” Q.E.D. !!

Slide 23

Slide 23 text

1. Opinion 2. Size 3. Age 4. Shape 5. Colour 6. Origin 7. Material 8. Purpose English has complex grammar rules … Adjective order Green little men Little green men

Slide 24

Slide 24 text

1. Opinion 2. Size 3. Age 4. Shape 5. Colour 6. Origin 7. Material 8. Purpose English has complex grammar rules … Adjective order Green little men Little green men lovely little old long green French silver serving spoon

Slide 25

Slide 25 text

No one was ever taught this rule in school! Little green men Rachel and me went to the cinema Between you and I All debts are cleared between you and I Merchant of Venice Act 3 scene 2

Slide 26

Slide 26 text

? Little green men Rachel and I

Slide 27

Slide 27 text

Noam Chomsky Universal Grammar Humans are born with an innate understanding of grammar. Prescriptive grammar Descriptive grammar

Slide 28

Slide 28 text

Prescriptive Descriptive Arbitrary grammar rule that prescribes the way people should speak Vs. Innate grammar rule that describes the way people speak naturally Robert Lowth 1710 - 1787 Rachel and I went to the cinema Mark Forsyth 1977 - present

Slide 29

Slide 29 text

Readable Code?

Slide 30

Slide 30 text

Learning code readability Psychology of code readability Make your code easier to read with Functional Programming Google JavaScript Style Guide Idiomatic.js Rules Code Readability Literature

Slide 31

Slide 31 text

// bad function sayHi(name) { return 'How are you, ' + name + '?'; } // good function sayHi(name) { return `How are you, ${name}?`; } Airbnb JavaScript Style Guide: Template strings give you a readable, concise syntax ... “ ”

Slide 32

Slide 32 text

Prescriptive • Arbitrary • Opinions as facts • No evidence

Slide 33

Slide 33 text

Prescriptive Descriptive

Slide 34

Slide 34 text

No native speakers of: JavaScript Python C / C++ Ruby Java Universal grammar applies to native language speakers Flaw in the metaphor Baṣa Jawa

Slide 35

Slide 35 text

Descriptive rules beneﬁcial?

Slide 36

Slide 36 text

Descriptive rules beneﬁcial?

Slide 37

Slide 37 text

Descriptive rules? • Based on empirical evidence • Describe how developers read / write code • Based on behaviour rather than opinion Ask a developer how readable they find code Measure how easily they can read code

Slide 38

Slide 38 text

Niall Coleman Clarke - Daniel van Berzon - Jake 'Sid' Smith

Slide 39

Slide 39 text

Online experiment to find descriptive rules for code readability Measures readability of coding constructs Showing code snippets to developers Measuring how easily they read them .com

Slide 40

Slide 40 text

Metric for readability? Can a developer predict output of code? Time it takes them to understand the code

Slide 41

Slide 41 text

No content

Slide 42

Slide 42 text

No content

Slide 43

Slide 43 text

No content

Slide 44

Slide 44 text

No content

Slide 45

Slide 45 text

Chaining a.b.c x = a.b x.c Methodology

Slide 46

Slide 46 text

Chaining a.b.c x = a.b x.c Methodology

Slide 47

Slide 47 text

Chaining 75% 50% } } a.b.c x = a.b x.c Methodology

Slide 48

Slide 48 text

11 Experiments Each testing a different coding construct 6 Exercises chaining methods

Slide 49

Slide 49 text

function sort(input) { var lowerCase = input.toLowerCase(); var lettersArray = lowerCase.split(''); var sorted = lettersArray.sort(); return sorted.join(''); } var result = sort('bag'); function sort(input) { return input .toLowerCase() .split('') .sort() .join(''); } var result = sort('bag'); Participant asked to predict value of result ES5? Chaining vs Intermediate

Slide 50

Slide 50 text

545 participants 10+ 6-10 5 4 3 2 1 <1 Years programming Main language Go C++ Kotlin Swift HTML/CSS Other Python Typescript Ruby C# Java PHP JavaScript

Slide 51

Slide 51 text

Results

Slide 52

Slide 52 text

Chaining vs Intermediate 89.2% 93.8% 30.5s 39.3s Statistical analysis

Slide 53

Slide 53 text

Chi-Squared test Students T-test P value P < 0.05 Chaining vs Intermediate

Slide 54

Slide 54 text

Chaining vs Intermediate 89.2% 93.8% 30.5s 39.3s

Slide 55

Slide 55 text

P = 0.044 P = 0.001 Chaining vs Intermediate 89.2% 93.8% 30.5s 39.3s

Slide 56

Slide 56 text

Slide 57

Slide 57 text

Naming There are only two hard things in Computer Science: cache invalidation and naming things. - Phil Karlton

Slide 58

Slide 58 text

array.filter(fn) Filtrate Residue

Slide 59

Slide 59 text

Generic vs Specific naming function sortAlphabetically(str) { return str .split('') .sort() .join(''); } var result = sortAlphabetically('made'); function processStr(str) { return str .split('') .sort() .join(''); } var result = processStr('made');

Slide 60

Slide 60 text

Generic vs Specific naming 95.3% 97.6% 18.7s 19.9s P = 0.045 P = 0.125

Slide 61

Slide 61 text

High P value? • No effect to measure Specific naming has no affect on time taken to read the code • Effect too small • Sample size is too low • Flaw in methodology

Slide 62

Slide 62 text

Constructs: Chaining methods Operator precedence Pure functions Abstraction Boolean algebra If statements Naming Ternary operators Inline functions Early return Comments

Slide 63

Slide 63 text

8/2*(2+2) (8/2)*(2+2) =16 8/(2*(2+2)) =1 Operator precedence Operator precedence

Slide 64

Slide 64 text

Precedence vs Brackets var fixed = 200; var monthly = 20; var result = fixed + (monthly * 12); var fixed = 200; var monthly = 20; var result = fixed + monthly * 12;

Slide 65

Slide 65 text

91.7% 97.2% 19.1s 17.0s P = 0.014 P = 0.042 Precedence vs Brackets

Slide 66

Slide 66 text

var fixed = 200; var monthly = 20; var result = fixed + (monthly * 12); var fixed = 200; var monthly = 20; var result = fixed + monthly * 12; Precedence vs Brackets

Slide 67

Slide 67 text

Order of if statements Prefer dealing with the positive case first instead of the negative. if (yes) { // foo } else { // bar } if (no) { // bar } else { // foo }

Slide 68

Slide 68 text

Positive vs Negative branch ﬁrst function canLegallyDrink(age) { var legal = age >= 18; if (legal) { return 'yes'; } else { return 'no'; } } var result = canLegallyDrink(14); function canLegallyDrink(age) { var legal = age >= 18; if (!legal) { return 'no'; } else { return 'yes'; } } var result = canLegallyDrink(14);

Slide 69

Slide 69 text

Pure functions var score = 10; function doubleScore() { score = score * 2; } doubleScore(); var result = score; Impure

Slide 70

Slide 70 text

var score = 10; function doubleScore(initialScore) { return initialScore * 2; } var result = doubleScore(score); Pure functions Pure

Slide 71

Slide 71 text

Impure vs Pure var score = 10; function doubleScore(initialScore) { return initialScore * 2; } var result = doubleScore(score); var score = 10; function doubleScore() { score = score * 2; } doubleScore(); var result = score;

Slide 72

Slide 72 text

Inline vs Function function getAverage(values) { var sum = 0; for (var i = 0; i < values.length; i++) { sum += values[i]; } return sum / values.length; } result = getAverage([1, 2, 3]); function getSum(values) { var sum = 0; for (var i = 0; i < values.length; i++) { sum += values[i]; } return sum; } function getAverage(values) { return getSum(values) / values.length; } result = getAverage([1, 2, 3]);

Slide 73

Slide 73 text

!a && !b === !(a || b) Boolean Algebra Expanded vs Simplified

Slide 74

Slide 74 text

Publish full results https://howreadable.com Dec 2019

Slide 75

Slide 75 text

Future

Slide 76

Slide 76 text

Limitations of experiment • Code snippets have to be self contained and small • Exercises are not realistic • Larger scale factors impossible to test Consistency - Approach - Organisation • Metrics are too simplistic

Slide 77

Slide 77 text

Improvements • Explore different methodologies - Ask developers change code • Increase participation: 1000+ • Analysis of existing code • Get help ... and funding.

Slide 78

Slide 78 text

Takeaways • Descriptive > Prescriptive • Possible to objectively measure readability • Question arbitrary rules • If in doubt, try it out • Help us! [email protected]

Slide 79

Slide 79 text

Thank Jake 'Sid' Smith Niall Coleman Clarke Narani van Laarhoven Freyja Nash Phil Teare Cian Campbell Oskar Holm Daniel van Berzon @dvberzon vanberzon.com howreadable.com you @ocastahq ocasta.com