Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Features
Speaker Deck
PRO
Sign in
Sign up for free
Search
Search
RuhrJS 2016: InchJS
Search
René Föhring
July 02, 2016
Programming
0
62
RuhrJS 2016: InchJS
René Föhring
July 02, 2016
Tweet
Share
More Decks by René Föhring
See All by René Föhring
ElixirConf.EU 2016: Credo - Analysing ASTs for Fun and Profit
rrrene
0
1.5k
ElixirRuhr.001: Good Tooling educates
rrrene
3
280
EuRuKo 2015: One Inch at a Time - How to get People excited about Inline Docs
rrrene
4
1.9k
Other Decks in Programming
See All in Programming
pytest プラグインを開発して DRY に自動テストを書こう
inuatsu
2
260
ML-прайсинг_на_Lamoda__вошли_и_вышли__приключение_на_20_минут__Слава_Цыганков.pdf
lamodatech
0
180
学生の時に開催したPerl入学式をきっかけにエンジニアが組織に馴染むために勉強会を主催や仲間と参加して職能間の境界を越えていく
ohmori_yusuke
1
140
Subclassing, Composition, Python, and You
hynek
3
170
モジュラモノリス、その前に / Modular monolith, before that
euglena1215
6
710
ビット演算の話 / Let's play with bit operations
kaityo256
PRO
4
180
実務未経験からいち早く戦力化するための新人エンジニア育成術 ~ 具体的な方法と育成する側の心得 ~
juri_matsuda
0
110
"noncopyable types" の使いどころについて考えてみた
andpad
0
160
Real-time message handling and notifications with API Platform and Symfony
alli83
1
110
WEBアプリケーションにおけるAWS Lambdaを用いた大規模な非同期処理の実践
delhi09
PRO
7
4.2k
게임 개발하던 학생이이 세계에선 안드로이드 개발자?
pangmoo
0
110
GrafanaのHTTP API を眺めてみよう
rinchoku
0
130
Featured
See All Featured
Building an army of robots
kneath
302
42k
Responsive Adventures: Dirty Tricks From The Dark Corners of Front-End
smashingmag
249
21k
Easily Structure & Communicate Ideas using Wireframe
afnizarnur
191
16k
For a Future-Friendly Web
brad_frost
174
9.3k
Creating an realtime collaboration tool: Agile Flush - .NET Oxford
marcduiker
25
1.7k
Design and Strategy: How to Deal with People Who Don’t "Get" Design
morganepeng
126
18k
Bash Introduction
62gerente
608
210k
Intergalactic Javascript Robots from Outer Space
tanoku
268
27k
Become a Pro
speakerdeck
PRO
24
4.9k
Building Adaptive Systems
keathley
38
2.2k
実際に使うSQLの書き方 徹底解説 / pgcon21j-tutorial
soudai
167
49k
Making Projects Easy
brettharned
115
5.9k
Transcript
How to get people excited about inline docs. InchJS René
Föhring // @rrrene inch-ci.org
How to get people excited about inline docs. InchJS René
Föhring // @rrrene inch-ci.org
@rrrene
@rrrene (read in pirate voice)
@rrrene (read in pirate voice) Coder @ Neopoly
https://www.neopoly.com/jobs/
https://www.neopoly.com/jobs/
https://www.neopoly.com/jobs/
Inline Docs?
// TODO: write some docs // function hash(filenameOrBlob, mode =
nil) { }
// Returns a hash for a given `filenameOrBlob`. // //
hash(filename) // => "68ac9064904d853a037a7a8f" function hash(filenameOrBlob, mode) { }
// Returns a hash for a given `filenameOrBlob`. // //
hash(filename) // => "68ac9064904d853a037a7a8f" function hash(filenameOrBlob, mode) { } free-form
/** * 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
// 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
(ง ͠° ͟ل ͜ ͡°)ง But what is the problem?
„good code is its own documentation“ (based on my early
twenties) versus „people are not JavaScript parsers“ (based on Zach Holman)
None
Tooling helps! because, there must be tools, right?
„There are 0 lines of documentation.“ or „65.7% documented“
Look, here are the facts.
Designing Inch Let‘s create a more opinionated tool.
First, let‘s make up some rules.
it is more important to document … longer functions than
short ones
it is more important to document … longer functions than
short ones functions with many parameters
it is more important to document … longer functions than
short ones functions with many parameters modules exporting functions
it is more important to document … longer functions than
short ones functions with many parameters modules containing functions ...
code objects ordered by priority 6 5 4 2 1
0 -1 -2 -3 -4 -5 -7
code objects ordered by priority 6 5 4 2 1
0 -1 -2 -3 -4 -5 -7
# These rules provide priorities for all # code objects.
const codeObjects = [ functions parameters ]; # ... which are also assigned a score. const scores = [0, 100];
# Called by the `initech` service. # # @return [undefined]
function userRegistered(username, _) { } Score: ? Priority: ?
# Called by the `initech` service. # # @return [undefined]
function userRegistered(username, _) { } Score: 90/100 Priority:
# Called by the `initech` service. # # @return [undefined]
function userRegistered(username, _) { } Score: 90/100 Priority:
# Called by the `initech` service. # # @return [undefined]
function userRegistered(username, _) { } Grade: A Priority:
>> require('grade_list').getAll() A – Really good B – Proper documentation
found C – Please take a look U – Undocumented (not a bad thing)
>> CLI _
# 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
# 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
>> inch suggest
>> inch suggest
>> inch list
>> inch show OBJECT_NAME
>> CLI !!!
>> CLI !!! but how to get people excited about
this?
BADGES
None
U C B A
None
None
None
None
2100x
2100x Ruby, JS & Elixir
The Things I learned
#1 Software is about people
#2 Be passionate about your ideas
#3 Be brave enough to build your own tools
The End (srsly, please help improving ES6 support)