Slide 1
Slide 1 text
How NOT to make your DSL
terrible
Red Dot Ruby Conference 2024
OKURA Masafumi, 2024-07-26
Slide 2
Slide 2 text
Hello,
RDRC 2024!
Slide 3
Slide 3 text
Hello,
Singapore!
Slide 4
Slide 4 text
Domain
Speci
fi
c
Language
Slide 5
Slide 5 text
Prelude
Slide 6
Slide 6 text
Programming
technique
DSL is a programming technique
Slide 7
Slide 7 text
Abstraction
Slide 8
Slide 8 text
Human-
understandable
Slide 9
Slide 9 text
DSL is for human
Slide 10
Slide 10 text
DSL is a friend of
Rubyists!
Slide 11
Slide 11 text
I love DSL!
Slide 12
Slide 12 text
https://www.reddit.com/r/ruby/comments/pyhig2/activeadmin_im_looking_at_you/
Slide 13
Slide 13 text
Some top comments on that Reddit post
• “I spend a lot of time reverse engineering some 34-GitHub-star
gem’s meta programming”
• “I know this is often an unpopular opinion, but I've grown to hate
DSL's. They are almost NEVER good, solve the wrong problem,
and generally badly.”
• “Most of the time, though, if I see a gem with a DSL, I try to
fi
nd
something else and only use the DSL based gem when its
absolutely necessary.”
Slide 14
Slide 14 text
How NOT to make your DSL
terrible
Red Dot Ruby Conference 2024
OKURA Masafumi, 2024-07-24
That's why I wanted to give this talk, to defend DSL
Slide 15
Slide 15 text
Today we are going to talk about:
1. What is DSL, why is it useful
2. Terrible DSL
3. Good DSL
4. General ideas NOT to make your DSL terrible
Slide 16
Slide 16 text
Dev.introduce self
• Name: OKURA Masafumi (Masafumi is the
fi
rst name)
• From: Tokyo, Japan
• Work as: freelancer
• Activities: Kaigi on Rails, Alba gem, public speaking (EuRuKo 2023,
RubyConfTw 2023, etc.), OSS contributions (Ruby/Rails/RDoc, etc.),
Rails Girls Coach (more than 10 times)
• Like: Clean code, refactoring, testing (RSpec and Minitest), DSL
Slide 17
Slide 17 text
Kaigi on Rails
Slide 18
Slide 18 text
Yet Another
Kaigi
Slide 19
Slide 19 text
No content
Slide 20
Slide 20 text
Rails/Web
Slide 21
Slide 21 text
The de
fi
nition of
success:
Slide 22
Slide 22 text
Becoming a
reason to choose
Rails
Slide 23
Slide 23 text
This year, it’s a
domestic
conference in
Japan
Slide 24
Slide 24 text
Next year…?
Slide 25
Slide 25 text
1. What is DSL,
Why is it useful
Slide 26
Slide 26 text
Domain
Speci
fi
c
Language
Slide 27
Slide 27 text
Domain
Speci
fi
c
Language
Slide 28
Slide 28 text
Example:
RSpec
Slide 29
Slide 29 text
Testing tool
Slide 30
Slide 30 text
DSL for “testing”
domain
Slide 31
Slide 31 text
No content
Slide 32
Slide 32 text
`describe`, `subject`,
`context`, `it`, `let`
and `is_expected` are
part of a “language”
Slide 33
Slide 33 text
English
language
Slide 34
Slide 34 text
They are all just
methods!
Slide 35
Slide 35 text
https://www.youtube.com/watch?v=Gk5n9lQGFG8
Slide 36
Slide 36 text
The de
fi
nition of
DSL in this talk:
Slide 37
Slide 37 text
A collection of
domain-related Ruby
methods that are
readable as English
Slide 38
Slide 38 text
No content
Slide 39
Slide 39 text
Why is it useful?
Slide 40
Slide 40 text
Ruby methods
that are readable
as English
Slide 41
Slide 41 text
Code, but also
document
Slide 42
Slide 42 text
Great
abstraction
Slide 43
Slide 43 text
Btw talk
(To me: if I need
more time, skip it)
Slide 44
Slide 44 text
Ruby is a great
language!
Slide 45
Slide 45 text
Ruby is a great
language!
… for DSL
Slide 46
Slide 46 text
Why?
Slide 47
Slide 47 text
3 reasons
Slide 48
Slide 48 text
3 reasons why Ruby is great for DSL
• Parenthesis-less method call
• `describe(‘description’)` doesn’t look like DSL, more programs
• Block
• It structures DSL with variety of ways, and `do~end` doesn’t
interrupt our reading, `{}` style is even better
• Less restrictions of naming
• `if` option works, `update!` and `updated?` work
Slide 49
Slide 49 text
2. Terrible DSL
Slide 50
Slide 50 text
Can DSL be
TERRIBLE??
Slide 51
Slide 51 text
No content
Slide 52
Slide 52 text
Example?
Slide 53
Slide 53 text
I don’t want to
blame anyone
Slide 54
Slide 54 text
The exception
Slide 55
Slide 55 text
Rails!
Slide 56
Slide 56 text
`accepts_nested_
attributes_for`
Slide 57
Slide 57 text
No content
Slide 58
Slide 58 text
https://github.com/rails/rails/pull/26976#discussion_r87855694
Slide 59
Slide 59 text
Why?
Slide 60
Slide 60 text
Why is it bad?
• You cannot tell what happens from DSL name
• It’s a “language”, so it’s useless unless we all know what it means
• It does too many things
• It involves Model, View and Controller
• Limited customizability
• Hard-to-remember options, still not possible for full customization
Slide 61
Slide 61 text
https://github.com/rails/rails/blob/v7.2.0.beta3/activerecord/lib/active_record/nested_attributes.rb
Slide 62
Slide 62 text
Another,
arti
fi
cial
example
Slide 63
Slide 63 text
Admin DSL
Slide 64
Slide 64 text
No content
Slide 65
Slide 65 text
No content
Slide 66
Slide 66 text
Why is it (so)
bad?
Slide 67
Slide 67 text
Why is it (so) bad?
• You cannot tell what happens from DSL name
• `crud` de
fi
nes 7 actions, maybe? Or, maybe 4?
• It does too many things
• It creates controllers and views
• Limited customizability
• How to de
fi
ne custom views or actions?
Slide 68
Slide 68 text
The common
characteristics of
terrible DSL
Slide 69
Slide 69 text
Bad naming and
complexity
Slide 70
Slide 70 text
3. Good DSL
Slide 71
Slide 71 text
Example?
Slide 72
Slide 72 text
Shameless
Self
Promotion
Slide 73
Slide 73 text
Alba
https://github.com/okuramasafumi/alba
Slide 74
Slide 74 text
JSON serializer
Slide 75
Slide 75 text
Alba code here
Slide 76
Slide 76 text
No content
Slide 77
Slide 77 text
Why is it good (as far as I believe)
• Predictable and understandable
• `attributes` declaring “attributes” for the object
• `association` and `nested` are straightforward
• `root_key` de
fi
nes a root key
• Each DSL has one thing to do
• Easy-to-understand options
Slide 78
Slide 78 text
No content
Slide 79
Slide 79 text
Why?
Slide 80
Slide 80 text
The nature of the
given domain
Slide 81
Slide 81 text
“JSON
serialization” is
simple, isolated
and self-contained
Slide 82
Slide 82 text
Rails has very
good DSL
methods
Slide 83
Slide 83 text
has_many
validates
resources
Slide 84
Slide 84 text
association
validation
RESTful routes
Slide 85
Slide 85 text
These domains
are simple,
isolated and
self-contained
Slide 86
Slide 86 text
Domain
Speci
fi
c
Language
Slide 87
Slide 87 text
Good DSL has a target domain that is…
• simple
• Usually one word or a short phrase, such as “ JSON serialization”
• isolated
• It doesn't affect other domains in a complex way
• self-contained
• You don’t have to know other things than the domain
Slide 88
Slide 88 text
JSON serialization domain is…
• simple
• One short phrase
• isolated
• Input is an object, output is the JSON representation
• self-contained
• You don’t have to be familiar with Rails controller to use Alba
Slide 89
Slide 89 text
No content
Slide 90
Slide 90 text
Well-known
words
Slide 91
Slide 91 text
“attributes”,
“has_many”,
“validates”
Slide 92
Slide 92 text
Intuitive
Slide 93
Slide 93 text
Readable
Slide 94
Slide 94 text
Understandable
Slide 95
Slide 95 text
Domain
Speci
fi
c
Language
Slide 96
Slide 96 text
No content
Slide 97
Slide 97 text
DSL is a
collection of
methods
Slide 98
Slide 98 text
Methods have
options
Slide 99
Slide 99 text
Options are
important
Slide 100
Slide 100 text
It’s the only way
to change how it
works
Slide 101
Slide 101 text
Too many
options hurt
Slide 102
Slide 102 text
But we want
fl
exibility!
Slide 103
Slide 103 text
Too many DSL
methods?
Slide 104
Slide 104 text
It depends
Slide 105
Slide 105 text
Alba code here
Slide 106
Slide 106 text
Details of options and methods from Alba
• Alba provides `if` option instead of `conditional_attributes` method
• `if` option is intuitive, not worth adding another DSL method
• Alba provides `nested` method instead of `nested` option
• `nested` option didn’t make sense (at least to me)
• `if` option is applied to `attributes`, `attribute` and `association`
• Inference works, easy to remember
Slide 107
Slide 107 text
The common
characteristics of
good DSL
Slide 108
Slide 108 text
Good naming
and simplicity
Slide 109
Slide 109 text
4. General ideas
NOT to make
your DSL terrible
Slide 110
Slide 110 text
General ideas NOT to make your DSL terrible
1. Stop and think again about whether it’s a simple, isolated and self-
contained domain
1. If the domain is too complex or intricate, just use normal code
2. Keep each DSL method simple and let them do one thing well
1. Pick the right word that’s intuitive, readable and understandable
3. Provide options so that it’s
fl
exible enough to customize
1. Options also should be intuitive
Slide 111
Slide 111 text
Rule of thumb
Slide 112
Slide 112 text
Naming
Slide 113
Slide 113 text
Good naming
• One, dictionary-de
fi
ned word is always preferable
• “association” is better than “de
fi
ne_association”
• Do not use self-invented word unless it’s a ubiquitous language
• Users of the DSL must understand it
• Verbs/nouns for DSL methods, adverbs/adjectives for options
• `attributes :some, if: …`, `has_many :books, through: …`
Slide 114
Slide 114 text
Complexity
Slide 115
Slide 115 text
10 lines of code
to implement
DSL method
Slide 116
Slide 116 text
Wait,
Slide 117
Slide 117 text
Is it just a normal
programming??
Slide 118
Slide 118 text
There are only two hard
things in Computer
Science: cache invalidation
and naming things.
-- Phil Karlton
Slide 119
Slide 119 text
Sandi Metz'
Rules
Slide 120
Slide 120 text
No content
Slide 121
Slide 121 text
Because…
Slide 122
Slide 122 text
Postlude
Slide 123
Slide 123 text
DSL is a
programming
technique
Slide 124
Slide 124 text
DSL is a way of
abstraction
Slide 125
Slide 125 text
Ruby gives us
the power of
DSL
Slide 126
Slide 126 text
DSL is a tool
Slide 127
Slide 127 text
DSL is NOT for
everything
Slide 128
Slide 128 text
Power
with
responsibility
Slide 129
Slide 129 text
Use DSL smart,
do it for human,
happy hacking!
Slide 130
Slide 130 text
Extra zone
(If 30 mins have
passed,
fi
nish it)
Slide 131
Slide 131 text
Do you want
someone who is
good at DSL?
Slide 132
Slide 132 text
Do you want an
enthusiastic
Rubyist from JST
timezone?
Slide 133
Slide 133 text
Do you want a
technical partner
who speaks native
Japanese?
Slide 134
Slide 134 text
Hire me!
… maybe not,
but talk to me!
https://www.linkedin.com/in/masafumi-
okura-82651128/
https://ruby.social/@okuramasafumi
Slide 135
Slide 135 text
Thank you!