Readable code - available without prescription

This talk tells the story of a revolution in the world of linguistics and how we can apply it to software development. Everyone agrees on the importance of readable code, but no-one can agree on how to write it. There are many conflicting rules out there, and they are all opinionated and arbitrary. Grammar is also full of rules, and not all rules are the same. “Prescriptive” rules are hard to follow. “Descriptive” rules are intuitive. With the help of Shakespeare, Noam Chomsky and some little green men, we will learn the dangers of prescriptive rules, and discover howreadable.com, an online scientific experiment that can help us write readable code.

Presented at FrontCon 2020
https://2020.frontcon.com/sessions/readable-code-available-without-prescription/

Transcript

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

   View Slide

2. Grammar
   

   View Slide

3. View Slide

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

   View Slide

5. Readable Code
   

   View Slide

6. View Slide

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

   View Slide

8. Grammar Readable Code
   

   View Slide

9. .com
   

   View Slide

10. Readable Code
    

    View Slide

11. Writing code
    On your own
    For the computer
    Student
    

    View Slide

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

    View Slide

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

    View Slide

14. … is hard to write
    Code that is easy to read
    

    View Slide

15. const = 0;
    z
    Too Many Options
    

    View Slide

16. Spoilers
    

    View Slide

17. Other People
    

    View Slide

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

    View Slide

19. Readability
    Structure
    Consistency
    Brevity
    Convention
    Syntax
    Naming
    Clarity
    Approach
    

    View Slide

20. Rules?
    Structure
    Consistency
    Brevity
    Convention
    Syntax
    Naming
    Clarity
    Approach
    

    View Slide

21. Grammar
    

    View Slide

22. Grammar
    English
    !"#$
    %&'(
    )*+,
    -.
    

    View Slide

23. Grumpy Language Teacher
    

    View Slide

24. "Never end a sentence
    with a preposition!"
    

    View Slide

25. What is he on about?
    preposition
    About what is he on?
    On about what is he? /
    

    View Slide

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

    View Slide

27. B: Rachel and I went to
    the cinema
    2 words for referring to oneself
    “I” (subject): “I went to the cinema”
    “Me” (object): "Rachel noticed me”
    “Rachel” and “I” are both subjects
    “Rachel and I went to the cinema”
    So there!!
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

31. ?
    Little green men Rachel and I
    

    View Slide

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

    View Slide

33. Prescriptive grammar rule
    Arbitrary rule that prescribes
    how people should speak
    Robert Lowth
    1710 - 1787
    Rachel and I went
    to the cinema
    

    View Slide

34. Descriptive grammar rule
    Instinctive grammar rule
    that describes how people
    speak naturally
    Mark Forsyth
    1977 - present
    

    View Slide

35. Prescriptive Descriptive
    Vs.
    Rachel and I went
    to the cinema
    How people
    Should speak
    How people
    speak naturally
    

    View Slide

36. Readable Code?
    

    View Slide

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

    View Slide

38. // 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 ...
    “
    ”
    

    View Slide

39. Prescriptive
    

    View Slide

40. Prescriptive
    • Arbitrary
    • Opinions as facts
    • No evidence
    

    View Slide

41. Prescriptive Descriptive
    

    View Slide

42. Readable code
    (Available without prescription)
    0
    

    View Slide

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

    View Slide

44. Descriptive rules beneficial?
    

    View Slide

45. Descriptive rules beneficial?
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

50. View Slide

51. View Slide

52. View Slide

53. View Slide

54. Methodology
    

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

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

    View Slide

63. Results
    

    View Slide

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

    View Slide

65. Chi-Squared test
    Welch's T-test
    P value P < 0.05
    Chaining vs Intermediate
    

    View Slide

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

    View Slide

67. 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');
    Chaining vs Intermediate
    

    View Slide

68. Constructs:
    Chaining methods
    Operator precedence
    If statements
    Pure functions
    Abstraction
    Boolean algebra
    Naming
    Ternary operators
    Inline functions
    Early return
    Comments
    P value too high
    

    View Slide

69. High P value?
    • No effect to measure
    • Effect too small
    • Sample size is too low
    • Flaw in methodology
    

    View Slide

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

    View Slide

71. 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;
    

    View Slide

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

    View Slide

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

    View Slide

74. var result = fixed + (monthly * 12); var result = fixed + monthly * 12;
    An opinionated
    code formatter
    

    View Slide

75. 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
    }
    

    View Slide

76. Positive vs Negative
    branch first
    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);
    

    View Slide

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

    View Slide

78. Full results and
    recommendations
    https://howreadable.com
    

    View Slide

79. Future
    

    View Slide

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

    View Slide

81. Improvements
    • Explore different methodologies
    - Ask developers change code
    • Increase participation: 1000+
    • Alternative approach?
    

    View Slide

82. Analysis of existing code
    Linguistic research by searching a language corpus
    https://books.google.com/ngrams
    

    View Slide

83. Get help
    ... and funding.
    

    View Slide

84. Takeaways
    • Descriptive > Prescriptive
    • Possible to objectively measure readability
    • Question arbitrary rules
    • Science is hard!
    • Help us!
    info@howreadable.com
    

    View Slide

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

    View Slide