RuhrJS 2016: InchJS

Transcript

1. 1.

   How to get people excited about inline docs. InchJS René

   Föhring // @rrrene inch-ci.org
2. 2.

   How to get people excited about inline docs. InchJS René

   Föhring // @rrrene inch-ci.org
3. 3.

   @rrrene

4. 4.

   @rrrene (read in pirate voice)

5. 5.

   @rrrene (read in pirate voice) Coder @ Neopoly

6. 6.

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

7. 7.

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

8. 8.

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

9. 9.

   Inline Docs?

10. 10.

    // TODO: write some docs // function hash(filenameOrBlob, mode =

    nil) { }
11. 11.

    // Returns a hash for a given `filenameOrBlob`. // //

    hash(filename) // => "68ac9064904d853a037a7a8f" function hash(filenameOrBlob, mode) { }
12. 12.

    // Returns a hash for a given `filenameOrBlob`. // //

    hash(filename) // => "68ac9064904d853a037a7a8f" function hash(filenameOrBlob, mode) { } free-form
13. 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
14. 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
15. 15.

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

16. 16.

    „good code is its own documentation“ (based on my early

    twenties) versus „people are not JavaScript parsers“ (based on Zach Holman)
17. 17.

    None
18. 18.

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

19. 19.

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

20. 20.

    Look, here are the facts.

21. 21.

    Designing Inch Let‘s create a more opinionated tool.

22. 22.

    First, let‘s make up some rules.

23. 23.

    it is more important to document … longer functions than

    short ones
24. 24.

    it is more important to document … longer functions than

    short ones functions with many parameters
25. 25.

    it is more important to document … longer functions than

    short ones functions with many parameters modules exporting functions
26. 26.

    it is more important to document … longer functions than

    short ones functions with many parameters modules containing functions ...
27. 27.

    code objects ordered by priority 6 5 4 2 1

    0 -1 -2 -3 -4 -5 -7
28. 28.

    code objects ordered by priority 6 5 4 2 1

    0 -1 -2 -3 -4 -5 -7
29. 29.

    # These rules provide priorities for all # code objects.

    const codeObjects = [ functions parameters ]; # ... which are also assigned a score. const scores = [0, 100];
30. 30.

    # Called by the `initech` service. # # @return [undefined]

    function userRegistered(username, _) { } Score: ? Priority: ?
31. 31.

    # Called by the `initech` service. # # @return [undefined]

    function userRegistered(username, _) { } Score: 90/100 Priority:
32. 32.

    # Called by the `initech` service. # # @return [undefined]

    function userRegistered(username, _) { } Score: 90/100 Priority:
33. 33.

    # Called by the `initech` service. # # @return [undefined]

    function userRegistered(username, _) { } Grade: A Priority:
34. 34.

    >> require('grade_list').getAll() A – Really good B – Proper documentation

    found C – Please take a look U – Undocumented (not a bad thing)
35. 35.

    >> CLI _

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

    >> inch suggest

39. 39.

    >> inch suggest

40. 40.

    >> inch list

41. 41.

    >> inch show OBJECT_NAME

42. 42.

    >> CLI !!!

43. 43.

    >> CLI !!! but how to get people excited about

    this?
44. 44.

    BADGES

45. 45.

    None
46. 46.

    U C B A

47. 47.

    None
48. 48.

    None
49. 49.

    None
50. 50.

    None
51. 51.

    2100x

52. 52.

    2100x Ruby, JS & Elixir

53. 53.

    The Things I learned

54. 54.

    #1 Software is about people

55. 55.

    #2 Be passionate about your ideas

56. 56.

    #3 Be brave enough to build your own tools

57. 57.

    The End (srsly, please help improving ES6 support)