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
RuhrJS 2016: InchJS
Search
René Föhring
July 02, 2016
Programming
0
62
RuhrJS 2016: InchJS
René Föhring
July 02, 2016
Tweet
Share
More Decks by René Föhring
See All by René Föhring
ElixirConf.EU 2016: Credo - Analysing ASTs for Fun and Profit
rrrene
0
1.5k
ElixirRuhr.001: Good Tooling educates
rrrene
3
290
EuRuKo 2015: One Inch at a Time - How to get People excited about Inline Docs
rrrene
4
1.9k
Other Decks in Programming
See All in Programming
アクターシステムに頼らずEvent Sourcingする方法について
j5ik2o
4
180
As an Engineers, let's build the CRM system via LINE Official Account 2.0
clonn
1
670
SymfonyCon Vienna 2025: Twig, still relevant in 2025?
fabpot
3
1.2k
快速入門可觀測性
blueswen
0
320
Zoneless Testing
rainerhahnekamp
0
120
StarlingMonkeyを触ってみた話 - 2024冬
syumai
3
270
第5回日本眼科AI学会総会_AIコンテスト_3位解法
neilsaw
0
170
Symfony Mapper Component
soyuka
2
730
テストコード文化を0から作り、変化し続けた組織
kazatohiei
2
1.5k
range over funcの使い道と非同期N+1リゾルバーの夢 / about a range over func
mackee
0
110
MCP with Cloudflare Workers
yusukebe
2
220
なまけものオバケたち -PHP 8.4 に入った新機能の紹介-
tanakahisateru
1
120
Featured
See All Featured
Cheating the UX When There Is Nothing More to Optimize - PixelPioneers
stephaniewalter
280
13k
Rebuilding a faster, lazier Slack
samanthasiow
79
8.7k
Creating an realtime collaboration tool: Agile Flush - .NET Oxford
marcduiker
26
1.9k
The Myth of the Modular Monolith - Day 2 Keynote - Rails World 2024
eileencodes
17
2.2k
Build The Right Thing And Hit Your Dates
maggiecrowley
33
2.4k
Making the Leap to Tech Lead
cromwellryan
133
9k
The Invisible Side of Design
smashingmag
298
50k
Build your cross-platform service in a week with App Engine
jlugia
229
18k
Bash Introduction
62gerente
608
210k
RailsConf & Balkan Ruby 2019: The Past, Present, and Future of Rails at GitHub
eileencodes
132
33k
Optimising Largest Contentful Paint
csswizardry
33
3k
Responsive Adventures: Dirty Tricks From The Dark Corners of Front-End
smashingmag
251
21k
Transcript
How to get people excited about inline docs. InchJS René
Föhring // @rrrene inch-ci.org
How to get people excited about inline docs. InchJS René
Föhring // @rrrene inch-ci.org
@rrrene
@rrrene (read in pirate voice)
@rrrene (read in pirate voice) Coder @ Neopoly
https://www.neopoly.com/jobs/
https://www.neopoly.com/jobs/
https://www.neopoly.com/jobs/
Inline Docs?
// TODO: write some docs // function hash(filenameOrBlob, mode =
nil) { }
// Returns a hash for a given `filenameOrBlob`. // //
hash(filename) // => "68ac9064904d853a037a7a8f" function hash(filenameOrBlob, mode) { }
// Returns a hash for a given `filenameOrBlob`. // //
hash(filename) // => "68ac9064904d853a037a7a8f" function hash(filenameOrBlob, mode) { } free-form
/** * Generates a hash for a given `filenameOrBlob`. *
* @example * hash(filename) * => "68ac9064904d853a037a7a8f“ * * @param filenameOrBlob [String] the filename * @param mode [String,null] optional mode * @return [String,null] */ function hash(filenameOrBlob, mode) { } JSDoc
// Public: Generates a hash for the blob. // //
filenameOrBlob – filename or blob // mode - Optional mode (defaults to "SHA1") // // Examples // // size(filename) // => "68ac9064904d853a037a7a8f“ // // Returns String or null. function hash(filenameOrBlob, mode) { } TomDoc
(ง ͠° ͟ل ͜ ͡°)ง But what is the problem?
„good code is its own documentation“ (based on my early
twenties) versus „people are not JavaScript parsers“ (based on Zach Holman)
None
Tooling helps! because, there must be tools, right?
„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 … longer functions than
short ones
it is more important to document … longer functions than
short ones functions with many parameters
it is more important to document … longer functions than
short ones functions with many parameters modules exporting functions
it is more important to document … longer functions than
short ones functions with many parameters modules containing functions ...
code objects ordered by priority 6 5 4 2 1
0 -1 -2 -3 -4 -5 -7
code objects ordered by priority 6 5 4 2 1
0 -1 -2 -3 -4 -5 -7
# These rules provide priorities for all # code objects.
const codeObjects = [ functions parameters ]; # ... which are also assigned a score. const scores = [0, 100];
# Called by the `initech` service. # # @return [undefined]
function userRegistered(username, _) { } Score: ? Priority: ?
# Called by the `initech` service. # # @return [undefined]
function userRegistered(username, _) { } Score: 90/100 Priority:
# Called by the `initech` service. # # @return [undefined]
function userRegistered(username, _) { } Score: 90/100 Priority:
# Called by the `initech` service. # # @return [undefined]
function userRegistered(username, _) { } Grade: A Priority:
>> require('grade_list').getAll() 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 show OBJECT_NAME
>> CLI !!!
>> CLI !!! but how to get people excited about
this?
BADGES
None
U C B A
None
None
None
None
2100x
2100x 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
The End (srsly, please help improving ES6 support)