RuhrJS 2016: InchJS

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)
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
46. U C B A
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)