Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Readable code - available without prescription

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/

Daniel van Berzon

August 14, 2020
Tweet

More Decks by Daniel van Berzon

Other Decks in Technology

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!
    [email protected]

    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