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
Reading Rails 1.0 Source Code
okuramasafumi
0
240
rage against annotate_predecessor
junk0612
0
170
AWS発のAIエディタKiroを使ってみた
iriikeita
1
190
250830 IaCの選定~AWS SAMのLambdaをECSに乗り換えたときの備忘録~
east_takumi
0
400
Deep Dive into Kotlin Flow
jmatsu
1
350
FindyにおけるTakumi活用と脆弱性管理のこれから
rvirus0817
0
520
Swift Updates - Learn Languages 2025
koher
2
490
Oracle Database Technology Night 92 Database Connection control FAN-AC
oracle4engineer
PRO
1
460
Design Foundational Data Engineering Observability
sucitw
3
200
ユーザーも開発者も悩ませない TV アプリ開発 ~Compose の内部実装から学ぶフォーカス制御~
taked137
0
180
Navigating Dependency Injection with Metro
zacsweers
3
1k
🔨 小さなビルドシステムを作る
momeemt
4
680
Featured
See All Featured
We Have a Design System, Now What?
morganepeng
53
7.8k
Visualizing Your Data: Incorporating Mongo into Loggly Infrastructure
mongodb
48
9.7k
Build your cross-platform service in a week with App Engine
jlugia
231
18k
Learning to Love Humans: Emotional Interface Design
aarron
273
40k
The MySQL Ecosystem @ GitHub 2015
samlambert
251
13k
The Power of CSS Pseudo Elements
geoffreycrofte
77
6k
Git: the NoSQL Database
bkeepers
PRO
431
66k
Automating Front-end Workflow
addyosmani
1370
200k
Designing Experiences People Love
moore
142
24k
Music & Morning Musume
bryan
46
6.8k
Build The Right Thing And Hit Your Dates
maggiecrowley
37
2.9k
Principles of Awesome APIs and How to Build Them.
keavy
126
17k
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