How NOT to make your DSL terrible

Presented at https://reddotrubyconf.com/
Video URL: [PLACEHOLDER]

If you're interested in DSL or you HATE DSL, this talk is for you.

1. How NOT to make your DSL terrible Red Dot Ruby Conference 2024 OKURA Masafumi, 2024-07-26
2. Hello, RDRC 2024!
3. Hello, Singapore!
4. Domain Speci fi c Language
5. Prelude
6. Programming technique DSL is a programming technique
7. Abstraction
8. Human- understandable
9. DSL is for human
10. DSL is a friend of Rubyists!
11. I love DSL!
12. https://www.reddit.com/r/ruby/comments/pyhig2/activeadmin_im_looking_at_you/
13. 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.”
14. 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
15. 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
16. 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
17. Kaigi on Rails
18. Yet Another Kaigi
20. Rails/Web
21. The de fi nition of success:
22. Becoming a reason to choose Rails
23. This year, it’s a domestic conference in Japan
24. Next year…?
25. 1. What is DSL, Why is it useful
26. Domain Speci fi c Language
27. Domain Speci fi c Language
28. Example: RSpec
29. Testing tool
30. DSL for “testing” domain
32. `describe`, `subject`, `context`, `it`, `let` and `is_expected` are part of a “language”
33. English language
34. They are all just methods!
35. https://www.youtube.com/watch?v=Gk5n9lQGFG8
36. The de fi nition of DSL in this talk:
37. A collection of domain-related Ruby methods that are readable as English
39. Why is it useful?
40. Ruby methods that are readable as English
41. Code, but also document
42. Great abstraction
43. Btw talk (To me: if I need more time, skip it)
44. Ruby is a great language!
45. Ruby is a great language! … for DSL
46. Why?
47. 3 reasons
48. 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
49. 2. Terrible DSL
50. Can DSL be TERRIBLE??
52. Example?
53. I don’t want to blame anyone
54. The exception
55. Rails!
56. `accepts_nested_ attributes_for`
58. https://github.com/rails/rails/pull/26976#discussion_r87855694
59. Why?
60. 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
61. https://github.com/rails/rails/blob/v7.2.0.beta3/activerecord/lib/active_record/nested_attributes.rb
62. Another, arti fi cial example
63. Admin DSL
66. Why is it (so) bad?
67. 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?
68. The common characteristics of terrible DSL
69. Bad naming and complexity
70. 3. Good DSL
71. Example?
72. Shameless Self Promotion
73. Alba https://github.com/okuramasafumi/alba
74. JSON serializer
75. Alba code here
77. 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
79. Why?
80. The nature of the given domain
81. “JSON serialization” is simple, isolated and self-contained
82. Rails has very good DSL methods
83. has_many validates resources
84. association validation RESTful routes
85. These domains are simple, isolated and self-contained
86. Domain Speci fi c Language
87. 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
88. 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
90. Well-known words
91. “attributes”, “has_many”, “validates”
92. Intuitive
93. Readable
94. Understandable
95. Domain Speci fi c Language
97. DSL is a collection of methods
98. Methods have options
99. Options are important
100. It’s the only way to change how it works
101. Too many options hurt
102. But we want fl exibility!
103. Too many DSL methods?
104. It depends
105. Alba code here
106. 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
107. The common characteristics of good DSL
108. Good naming and simplicity
109. 4. General ideas NOT to make your DSL terrible
110. 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
111. Rule of thumb
112. Naming
113. 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: …`
114. Complexity
115. 10 lines of code to implement DSL method
116. Wait,
117. Is it just a normal programming??
118. There are only two hard things in Computer Science: cache invalidation and naming things. -- Phil Karlton
119. Sandi Metz' Rules
121. Because…
122. Postlude
123. DSL is a programming technique
124. DSL is a way of abstraction
125. Ruby gives us the power of DSL
126. DSL is a tool
127. DSL is NOT for everything
128. Power with responsibility
129. Use DSL smart, do it for human, happy hacking!
130. Extra zone (If 30 mins have passed, fi nish it)
131. Do you want someone who is good at DSL?
132. Do you want an enthusiastic Rubyist from JST timezone?
133. Do you want a technical partner who speaks native Japanese?
134. Hire me! … maybe not, but talk to me! https://www.linkedin.com/in/masafumi- okura-82651128/ https://ruby.social/@okuramasafumi
135. Thank you!