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
1.9k
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
62
ElixirConf.EU 2016: Credo - Analysing ASTs for Fun and Profit
rrrene
0
1.5k
ElixirRuhr.001: Good Tooling educates
rrrene
3
280
Other Decks in Programming
See All in Programming
PHPを書く理由、PHPを書いていて良い理由 / Reasons to write PHP and why it is good to write PHP
seike460
PRO
5
460
実務未経験からいち早く戦力化するための新人エンジニア育成術 ~ 具体的な方法と育成する側の心得 ~
juri_matsuda
0
110
[KR] Server Driven Compose With Firebase
skydoves
2
190
Remix × Cloudflare Pages × Sentry 奮闘記 / remix-pages-sentry
nkzn
1
410
perl for shell, awk and sed programmers
mackee
1
680
Делим тесты между QA и разработчиком
lamodatech
0
550
RDBの世界をぬりかえていくモデルグラフDB〜truncus graphによるモデルファースト開発〜
jurabi
0
170
Pydantic x Database API:turu-pyの開発
yassun7010
1
570
文化が生産性を作る
jimpei
3
560
Subclassing, Composition, Python, and You
hynek
3
160
Cancel Next.js Page Navigation: Full Throttle
ypresto
1
170
ECS向けのドリフト検知機構を実装してみた
tkikuc
0
280
Featured
See All Featured
Fontdeck: Realign not Redesign
paulrobertlloyd
81
5.2k
CSS Pre-Processors: Stylus, Less & Sass
bermonpainter
355
29k
Helping Users Find Their Own Way: Creating Modern Search Experiences
danielanewman
29
2.2k
Become a Pro
speakerdeck
PRO
24
4.9k
Save Time (by Creating Custom Rails Generators)
garrettdimon
PRO
25
660
Facilitating Awesome Meetings
lara
49
6k
The Invisible Side of Design
smashingmag
297
50k
Typedesign – Prime Four
hannesfritz
39
2.3k
Side Projects
sachag
452
42k
Statistics for Hackers
jakevdp
796
220k
The Illustrated Children's Guide to Kubernetes
chrisshort
48
48k
Writing Fast Ruby
sferik
626
60k
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