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
65
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.6k
ElixirRuhr.001: Good Tooling educates
rrrene
3
340
EuRuKo 2015: One Inch at a Time - How to get People excited about Inline Docs
rrrene
4
2k
Other Decks in Programming
See All in Programming
The Niche of CDK Grant オブジェクトって何者?/the-niche-of-cdk-what-isgrant-object
hassaku63
1
610
ソフトウェア設計とAI技術の活用
masuda220
PRO
16
3.3k
GPUを計算資源として使おう!
primenumber
1
240
Goで作る、開発・CI環境
sin392
0
260
Agentic Coding: The Future of Software Development with Agents
mitsuhiko
0
130
システム成長を止めない!本番無停止テーブル移行の全貌
sakawe_ee
1
350
Flutterで備える!Accessibility Nutrition Labels完全ガイド
yuukiw00w
0
170
AI駆動のマルチエージェントによる業務フロー自動化の設計と実践
h_okkah
0
230
イベントストーミング図からコードへの変換手順 / Procedure for Converting Event Storming Diagrams to Code
nrslib
2
1.1k
ふつうの技術スタックでアート作品を作ってみる
akira888
1
1.3k
NPOでのDevinの活用
codeforeveryone
0
900
“いい感じ“な定量評価を求めて - Four Keysとアウトカムの間の探求 -
nealle
2
12k
Featured
See All Featured
Understanding Cognitive Biases in Performance Measurement
bluesmoon
29
1.8k
[RailsConf 2023 Opening Keynote] The Magic of Rails
eileencodes
29
9.6k
Dealing with People You Can't Stand - Big Design 2015
cassininazir
367
26k
Agile that works and the tools we love
rasmusluckow
329
21k
Into the Great Unknown - MozCon
thekraken
40
1.9k
Adopting Sorbet at Scale
ufuk
77
9.5k
Building an army of robots
kneath
306
45k
Designing Dashboards & Data Visualisations in Web Apps
destraynor
231
53k
How GitHub (no longer) Works
holman
314
140k
Keith and Marios Guide to Fast Websites
keithpitt
411
22k
CSS Pre-Processors: Stylus, Less & Sass
bermonpainter
357
30k
Fantastic passwords and where to find them - at NoRuKo
philnash
51
3.3k
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)