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
ドメイン駆動設計のエッセンス
masuda220
PRO
10
2.4k
ALL CODE BASE ARE BELONG TO STUDY
uzulla
28
6.7k
AI 駆動開発におけるコミュニティと AWS CDK の価値
konokenj
5
270
CSC305 Lecture 09
javiergs
PRO
0
310
コード生成なしでモック処理を実現!ovechkin-dm/mockioで学ぶメタプログラミング
qualiarts
0
270
bootcamp2025_バックエンド研修_WebAPIサーバ作成.pdf
geniee_inc
0
140
NixOS + Kubernetesで構築する自宅サーバーのすべて
ichi_h3
0
1.2k
When Dependencies Fail: Building Antifragile Applications in a Fragile World
selcukusta
0
110
TransformerからMCPまで(現代AIを理解するための羅針盤)
mickey_kubo
7
5.5k
Reactive Thinking with Signals and the Resource API
manfredsteyer
PRO
0
110
Devoxx BE - Local Development in the AI Era
kdubois
0
140
CSC509 Lecture 07
javiergs
PRO
0
250
Featured
See All Featured
Building a Scalable Design System with Sketch
lauravandoore
463
33k
個人開発の失敗を避けるイケてる考え方 / tips for indie hackers
panda_program
116
20k
Side Projects
sachag
455
43k
Documentation Writing (for coders)
carmenintech
75
5.1k
YesSQL, Process and Tooling at Scale
rocio
173
15k
Code Review Best Practice
trishagee
72
19k
Design and Strategy: How to Deal with People Who Don’t "Get" Design
morganepeng
132
19k
The Myth of the Modular Monolith - Day 2 Keynote - Rails World 2024
eileencodes
26
3.1k
The World Runs on Bad Software
bkeepers
PRO
72
11k
Responsive Adventures: Dirty Tricks From The Dark Corners of Front-End
smashingmag
253
22k
Navigating Team Friction
lara
190
15k
Making the Leap to Tech Lead
cromwellryan
135
9.6k
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)