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

RuhrJS 2016: InchJS

RuhrJS 2016: InchJS

René Föhring

July 02, 2016
Tweet

More Decks by René Föhring

Other Decks in Programming

Transcript

  1. How to get people excited about inline docs.
    InchJS
    René Föhring // @rrrene inch-ci.org

    View Slide

  2. How to get people excited about inline docs.
    InchJS
    René Föhring // @rrrene inch-ci.org

    View Slide

  3. @rrrene

    View Slide

  4. @rrrene
    (read in pirate voice)

    View Slide

  5. @rrrene
    (read in pirate voice)
    Coder @ Neopoly

    View Slide

  6. https://www.neopoly.com/jobs/

    View Slide

  7. https://www.neopoly.com/jobs/

    View Slide

  8. https://www.neopoly.com/jobs/

    View Slide

  9. Inline Docs?

    View Slide

  10. // TODO: write some docs
    //
    function hash(filenameOrBlob, mode = nil) {
    }

    View Slide

  11. // Returns a hash for a given `filenameOrBlob`.
    //
    // hash(filename)
    // => "68ac9064904d853a037a7a8f"
    function hash(filenameOrBlob, mode) {
    }

    View Slide

  12. // Returns a hash for a given `filenameOrBlob`.
    //
    // hash(filename)
    // => "68ac9064904d853a037a7a8f"
    function hash(filenameOrBlob, mode) {
    }
    free-form

    View Slide

  13. /**
    * Generates a hash for a given `filenameOrBlob`.
    *
    * @example
    * hash(filename)
    * => "68ac9064904d853a037a7a8f“
    *
    * @param filenameOrBlob [String] the filename
    * @param mode [String,null] optional mode
    * @return [String,null]
    */
    function hash(filenameOrBlob, mode) {
    }
    JSDoc

    View Slide

  14. // Public: Generates a hash for the blob.
    //
    // filenameOrBlob – filename or blob
    // mode - Optional mode (defaults to "SHA1")
    //
    // Examples
    //
    // size(filename)
    // => "68ac9064904d853a037a7a8f“
    //
    // Returns String or null.
    function hash(filenameOrBlob, mode) {
    }
    TomDoc

    View Slide

  15. (ง ͠° ͟ل
    ͜ ͡°)ง
    But what is the
    problem?

    View Slide

  16. „good code is its own documentation“
    (based on my early twenties)
    versus
    „people are not JavaScript parsers“
    (based on Zach Holman)

    View Slide

  17. View Slide

  18. Tooling helps!
    because, there must be tools, right?

    View Slide

  19. „There are 0 lines of documentation.“
    or
    „65.7% documented“

    View Slide

  20. Look, here are the facts.

    View Slide

  21. Designing Inch
    Let‘s create a more opinionated tool.

    View Slide

  22. First, let‘s make up some rules.

    View Slide

  23. it is more important to document …
    longer functions than short ones

    View Slide

  24. it is more important to document …
    longer functions than short ones
    functions with many parameters

    View Slide

  25. it is more important to document …
    longer functions than short ones
    functions with many parameters
    modules exporting functions

    View Slide

  26. it is more important to document …
    longer functions than short ones
    functions with many parameters
    modules containing functions
    ...

    View Slide

  27. code objects ordered by priority
    6
    5
    4
    2
    1
    0
    -1
    -2
    -3
    -4
    -5
    -7

    View Slide

  28. code objects ordered by priority
    6
    5
    4
    2
    1
    0
    -1
    -2
    -3
    -4
    -5
    -7

    View Slide

  29. # These rules provide priorities for all
    # code objects.
    const codeObjects = [
    functions
    parameters
    ];
    # ... which are also assigned a score.
    const scores = [0, 100];

    View Slide

  30. # Called by the `initech` service.
    #
    # @return [undefined]
    function userRegistered(username, _) {
    }
    Score: ?
    Priority: ?

    View Slide

  31. # Called by the `initech` service.
    #
    # @return [undefined]
    function userRegistered(username, _) {
    }
    Score: 90/100
    Priority:

    View Slide

  32. # Called by the `initech` service.
    #
    # @return [undefined]
    function userRegistered(username, _) {
    }
    Score: 90/100
    Priority:

    View Slide

  33. # Called by the `initech` service.
    #
    # @return [undefined]
    function userRegistered(username, _) {
    }
    Grade: A
    Priority:

    View Slide

  34. >> require('grade_list').getAll()
    A – Really good
    B – Proper documentation found
    C – Please take a look
    U – Undocumented (not a bad thing)

    View Slide

  35. >> CLI _

    View Slide

  36. # Properly documented, could be improved:
    ┃ 50 4 Foo#initialize
    ┃ 50 4 Foo.Bar
    # Please take a look:
    ┃ 37 4 Foo.API#initialize
    ┃ 25 2 Foo.CodeObject#initialize
    # Undocumented:
    ┃ 0 4 Foo.CLI
    ┃ 0 4 Foo.API#send_request

    View Slide

  37. # Properly documented, could be improved:
    ┃ B ↑ Foo#initialize
    ┃ B ↑ Foo.Bar
    # Please take a look:
    ┃ C ↑ Foo.API#initialize
    ┃ C ↗ Foo.CodeObject#initialize
    # Undocumented:
    ┃ U ↑ Foo.CLI
    ┃ U ↑ Foo.API#send_request

    View Slide

  38. >> inch suggest

    View Slide

  39. >> inch suggest

    View Slide

  40. >> inch list

    View Slide

  41. >> inch show OBJECT_NAME

    View Slide

  42. >> CLI !!!

    View Slide

  43. >> CLI !!!
    but how to get people excited about this?

    View Slide

  44. BADGES

    View Slide

  45. View Slide

  46. U
    C
    B
    A

    View Slide

  47. View Slide

  48. View Slide

  49. View Slide

  50. View Slide

  51. 2100x

    View Slide

  52. 2100x
    Ruby, JS & Elixir

    View Slide

  53. The Things I learned

    View Slide

  54. #1
    Software is about people

    View Slide

  55. #2
    Be passionate about your ideas

    View Slide

  56. #3
    Be brave enough to build your own tools

    View Slide

  57. The End
    (srsly, please help improving ES6 support)

    View Slide