RuhrJS 2016: InchJS

RuhrJS 2016: InchJS

Faf649a95c7b996e7b7071f85277b3e2?s=128

René Föhring

July 02, 2016
Tweet

Transcript

  1. 3.
  2. 11.

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

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

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

    hash(filename) // => "68ac9064904d853a037a7a8f" function hash(filenameOrBlob, mode) { } free-form
  4. 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
  5. 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
  6. 16.

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

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

    it is more important to document … longer functions than

    short ones functions with many parameters
  9. 25.

    it is more important to document … longer functions than

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

    it is more important to document … longer functions than

    short ones functions with many parameters modules containing functions ...
  11. 29.

    # These rules provide priorities for all # code objects.

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

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

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

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

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

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

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

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

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

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

    found C – Please take a look U – Undocumented (not a bad thing)
  17. 35.
  18. 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
  19. 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
  20. 44.
  21. 45.
  22. 46.
  23. 47.
  24. 48.
  25. 49.
  26. 50.
  27. 51.