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

RuhrJS 2016: InchJS

RuhrJS 2016: InchJS

Faf649a95c7b996e7b7071f85277b3e2?s=128

René Föhring

July 02, 2016
Tweet

Transcript

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

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

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

  4. @rrrene (read in pirate voice)

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

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

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

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

  9. Inline Docs?

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

    nil) { }
  11. // Returns a hash for a given `filenameOrBlob`. // //

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

    hash(filename) // => "68ac9064904d853a037a7a8f" function hash(filenameOrBlob, mode) { } free-form
  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. // 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. (ง ͠° ͟ل ͜ ͡°)ง But what is the problem?

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

    twenties) versus „people are not JavaScript parsers“ (based on Zach Holman)
  17. None
  18. Tooling helps! because, there must be tools, right?

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

  20. Look, here are the facts.

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

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

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

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

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

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

    short ones functions with many parameters modules containing functions ...
  27. code objects ordered by priority 6 5 4 2 1

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

    0 -1 -2 -3 -4 -5 -7
  29. # These rules provide priorities for all # code objects.

    const codeObjects = [ functions parameters ]; # ... which are also assigned a score. const scores = [0, 100];
  30. # Called by the `initech` service. # # @return [undefined]

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

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

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

    function userRegistered(username, _) { } Grade: A Priority:
  34. >> require('grade_list').getAll() A – Really good B – Proper documentation

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

  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. # 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. >> inch suggest

  39. >> inch suggest

  40. >> inch list

  41. >> inch show OBJECT_NAME

  42. >> CLI !!!

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

    this?
  44. BADGES

  45. None
  46. U C B A

  47. None
  48. None
  49. None
  50. None
  51. 2100x

  52. 2100x Ruby, JS & Elixir

  53. The Things I learned

  54. #1 Software is about people

  55. #2 Be passionate about your ideas

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

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