RuhrJS 2016: InchJS

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