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
デミカツ切り抜きで面倒くさいことはPythonにやらせよう
aokswork3
0
250
品質ワークショップをやってみた
nealle
0
590
釣り地図SNSにおける有料機能の実装
nokonoko1203
0
190
「ちょっと古いから」って避けてた技術書、今だからこそ読もう
mottyzzz
11
7k
大規模アプリのDIフレームワーク刷新戦略 ~過去最大規模の並行開発を止めずにアプリ全体に導入するまで~
mot_techtalk
1
470
pnpm に provenance のダウングレード を検出する PR を出してみた
ryo_manba
1
130
Catch Up: Go Style Guide Update
andpad
0
240
テーブル定義書の構造化抽出して、生成AIでDWH分析を試してみた / devio2025tokyo
kasacchiful
0
250
Reactive Thinking with Signals and the Resource API
manfredsteyer
PRO
0
100
登壇は dynamic! な営みである / speech is dynamic
da1chi
0
350
Devoxx BE - Local Development in the AI Era
kdubois
0
130
O Que É e Como Funciona o PHP-FPM?
marcelgsantos
0
120
Featured
See All Featured
Intergalactic Javascript Robots from Outer Space
tanoku
273
27k
Making the Leap to Tech Lead
cromwellryan
135
9.6k
The Straight Up "How To Draw Better" Workshop
denniskardys
238
140k
The Cult of Friendly URLs
andyhume
79
6.6k
CSS Pre-Processors: Stylus, Less & Sass
bermonpainter
359
30k
RailsConf & Balkan Ruby 2019: The Past, Present, and Future of Rails at GitHub
eileencodes
140
34k
Measuring & Analyzing Core Web Vitals
bluesmoon
9
630
Being A Developer After 40
akosma
91
590k
For a Future-Friendly Web
brad_frost
180
10k
[RailsConf 2023] Rails as a piece of cake
palkan
57
5.9k
Bootstrapping a Software Product
garrettdimon
PRO
307
110k
A Modern Web Designer's Workflow
chriscoyier
697
190k
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