Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Speaker Deck
PRO
Sign in
Sign up for free
EuRuKo 2015: One Inch at a Time - How to get People excited about Inline Docs
René Föhring
October 17, 2015
Programming
4
1.5k
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
37
ElixirConf.EU 2016: Credo - Analysing ASTs for Fun and Profit
rrrene
0
1.4k
ElixirRuhr.001: Good Tooling educates
rrrene
3
220
Other Decks in Programming
See All in Programming
Hono v3 - Do Everything, Run Anywhere, But Small, And Faster
yusukebe
4
120
Amazon QuickSightのアップデート -re:Invent 2022の復習&2022年ハイライト-
shogo452
0
200
PHPアプリケーションにおけるアーキテクチャメトリクスについて / Architecture Metrics in PHP Applications
isanasan
1
210
フロントエンドで学んだことをデータ分析で使ってみた話
daichi_igarashi
0
170
Amebaブログの会員画面システム刷新の道程
ryotasugawara
1
210
SHOWROOMの分析目的を意識した伝え方・コミュニケーション
hatapu
0
230
AWS App Runnerがそろそろ本番環境でも使い物になりそう
n1215
PRO
0
870
Cloudflare Workersと状態管理
chimame
2
470
新卒でサービス立ち上げから Hasuraを使って3年経った振り返り
yutorin
0
200
Quarto Tips for Academic Presentation
nicetak
0
890
jq at the Shortcuts
cockscomb
1
390
フロントエンドで 良いコードを書くために
t_keshi
3
1.6k
Featured
See All Featured
Become a Pro
speakerdeck
PRO
6
3.2k
Designing for Performance
lara
600
65k
Designing the Hi-DPI Web
ddemaree
273
32k
KATA
mclloyd
12
9.7k
Rebuilding a faster, lazier Slack
samanthasiow
69
7.5k
Six Lessons from altMBA
skipperchong
15
2.3k
Building Flexible Design Systems
yeseniaperezcruz
314
35k
Design by the Numbers
sachag
271
18k
"I'm Feeling Lucky" - Building Great Search Experiences for Today's Users (#IAC19)
danielanewman
217
21k
The Art of Programming - Codeland 2020
erikaheidi
35
11k
Visualization
eitanlees
128
12k
What the flash - Photography Introduction
edds
64
10k
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