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
66
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.6k
ElixirRuhr.001: Good Tooling educates
rrrene
3
350
EuRuKo 2015: One Inch at a Time - How to get People excited about Inline Docs
rrrene
4
2.2k
Other Decks in Programming
See All in Programming
「ちょっと古いから」って避けてた技術書、今だからこそ読もう
mottyzzz
12
7.2k
Blazing Fast UI Development with Compose Hot Reload (Bangladesh KUG, October 2025)
zsmb
1
340
CSC509 Lecture 06
javiergs
PRO
0
270
なんでRustの環境構築してないのにRust製のツールが動くの? / Why Do Rust-Based Tools Run Without a Rust Environment?
ssssota
14
47k
Domain-centric? Why Hexagonal, Onion, and Clean Architecture Are Answers to the Wrong Question
olivergierke
3
980
Software Architecture
hschwentner
6
2.3k
Vueのバリデーション、結局どれを選べばいい? ― 自作バリデーションの限界と、脱却までの道のり ― / Which Vue Validation Library Should We Really Use? The Limits of Self-Made Validation and How I Finally Moved On
neginasu
2
1.6k
SwiftDataを使って10万件のデータを読み書きする
akidon0000
0
240
釣り地図SNSにおける有料機能の実装
nokonoko1203
0
200
iOSでSVG画像を扱う
kishikawakatsumi
0
170
Towards Transactional Buffering of CDC Events @ Flink Forward 2025 Barcelona Spain
hpgrahsl
0
120
Leading Effective Engineering Teams in the AI Era
addyosmani
7
660
Featured
See All Featured
個人開発の失敗を避けるイケてる考え方 / tips for indie hackers
panda_program
116
20k
VelocityConf: Rendering Performance Case Studies
addyosmani
333
24k
What’s in a name? Adding method to the madness
productmarketing
PRO
24
3.7k
Stop Working from a Prison Cell
hatefulcrawdad
272
21k
StorybookのUI Testing Handbookを読んだ
zakiyama
31
6.2k
How to Create Impact in a Changing Tech Landscape [PerfNow 2023]
tammyeverts
55
3k
The Language of Interfaces
destraynor
162
25k
Making Projects Easy
brettharned
120
6.4k
Why You Should Never Use an ORM
jnunemaker
PRO
59
9.6k
How to Ace a Technical Interview
jacobian
280
24k
ピンチをチャンスに:未来をつくるプロダクトロードマップ #pmconf2020
aki_iinuma
127
54k
Faster Mobile Websites
deanohume
310
31k
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)