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
EuRuKo 2015: One Inch at a Time - How to get Pe...
Search
René Föhring
October 17, 2015
Programming
4
2.1k
EuRuKo 2015: One Inch at a Time - How to get People excited about Inline Docs
René Föhring
October 17, 2015
Tweet
Share
More Decks by René Föhring
See All by René Föhring
RuhrJS 2016: InchJS
rrrene
0
66
ElixirConf.EU 2016: Credo - Analysing ASTs for Fun and Profit
rrrene
0
1.6k
ElixirRuhr.001: Good Tooling educates
rrrene
3
350
Other Decks in Programming
See All in Programming
私はどうやって技術力を上げたのか
yusukebe
43
17k
株式会社 Sun terras カンパニーデック
sunterras
0
200
ABEMAモバイルアプリが Kotlin Multiplatformと歩んだ5年 ─ 導入と運用、成功と課題 / iOSDC 2025
akkyie
0
320
CSC305 Lecture 04
javiergs
PRO
0
230
ИИ-Агенты в каждый дом – Алексей Порядин, PythoNN
sobolevn
0
150
Web技術を最大限活用してRAW画像を現像する / Developing RAW Images on the Web
ssssota
2
1.1k
麻雀点数計算問題生成タスクから学ぶ Single Agentの限界と Agentic Workflowの底力
po3rin
5
2.1k
Django Ninja による API 開発効率化とリプレースの実践
kashewnuts
0
900
Back to the Future: Let me tell you about the ACP protocol
terhechte
0
130
エンジニアとして高みを目指す、 利益を生み出す設計の考え方 / design-for-profit
minodriven
23
12k
ソフトウェア設計の実践的な考え方
masuda220
PRO
3
420
overlayPreferenceValue で実現する ピュア SwiftUI な AdMob ネイティブ広告
uhucream
0
100
Featured
See All Featured
個人開発の失敗を避けるイケてる考え方 / tips for indie hackers
panda_program
114
20k
Reflections from 52 weeks, 52 projects
jeffersonlam
352
21k
Speed Design
sergeychernyshev
32
1.1k
[RailsConf 2023] Rails as a piece of cake
palkan
57
5.9k
How to train your dragon (web standard)
notwaldorf
96
6.3k
Docker and Python
trallard
46
3.6k
The World Runs on Bad Software
bkeepers
PRO
71
11k
The Pragmatic Product Professional
lauravandoore
36
6.9k
Building an army of robots
kneath
306
46k
Code Review Best Practice
trishagee
72
19k
How to Ace a Technical Interview
jacobian
280
23k
Automating Front-end Workflow
addyosmani
1371
200k
Transcript
How to get people excited about inline docs. One Inch
at a Time René Föhring // @rrrene inch-ci.org
How to get people excited about inline docs. One Inch
at a Time René Föhring // @rrrene inch-ci.org
@rrrene
@rrrene (read in pirate voice)
@rrrene (read in pirate voice) coder ∙ teacher ∙ researcher
(insert more self-description here)
@rrrene creator of Inch / running Inch CI
Inline Docs?
# TODO: write some docs # def size(filename_or_blob, mode =
nil) end
# Returns the size of a given +filename_or_blob+. # #
size(filename) # => 4096 # def size(filename_or_blob, mode = nil) end
# Returns the size of a given +filename_or_blob+. # #
size(filename) # => 4096 # def size(filename_or_blob, mode = nil) end free-form
# Detects the size of the blob. # # size(filename)
# => 4096 # # Params: # +filename_or_blob+:: String filename or blob # +mode+:: Optional mode (defaults to nil) def size(filename_or_blob, mode = nil) end RDoc
# Detects the size of the blob. # # @example
# size(filename) # => 4096 # # @param filename_or_blob [String] the filename # @param mode [String, nil] optional mode # @return [Fixnum,nil] def size(filename_or_blob, mode = nil) end YARD
# Public: Detects the size of the blob. # #
filename_or_blob – filename or blob # mode - Optional mode (defaults to nil) # # Examples # # size(filename) # => 4096 # # Returns Fixnum or nil. def size(filename_or_blob, mode = nil) end TomDoc
(ง ͠° ͟ل ͜ ͡°)ง But what is the problem?
„good code is its own documentation“ (myself ten years ago)
versus „people are not Ruby parsers“ (Zach Holman)
Tooling helps! because, there must be tools, right?
None
None
„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 … public methods than
private ones
it is more important to document … public methods than
private ones methods with many parameters
it is more important to document … public methods than
private ones methods with many parameters modules containing methods
it is more important to document … public methods than
private ones methods with many parameters modules containing methods ...
code objects ordered by priority 4 4 4 2 2
0 -1 -2 -2 -4 -5 -7
code objects ordered by priority 4 4 4 2 2
0 -1 -2 -2 -4 -5 -7
# These rules provide priorities for all # code objects.
CODE_OBJECTS = %w( classes modules constants methods parameters ) # ... which are also assigned a score. SCORES = (0..100)
# Called by the `initech` gem. # # @return [void]
def user_registered(username, _) end Score: ? Priority: ?
# Called by the `initech` gem. # # @return [void]
def user_registered(username, _) end Score: 90/100 Priority:
# Called by the `initech` gem. # # @return [void]
def user_registered(username, _) end Score: 90/100 Priority:
# Called by the `initech` gem. # # @return [void]
def user_registered(username, _) end Grade: A Priority:
>> GradeList.all 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 diff
>> inch show OBJECT_NAME
>> CLI !!!
>> CLI !!! but how to get people excited about
this?
BADGES
None
U C B A
None
None
None
None
1500x
1500x 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
#4 Make it useful, accessible and beautiful
#5 Share the lessons you‘ve learned
How to get people excited about inline docs. One Inch
at a Time inch-ci.org René Föhring // @rrrene