1 .. SPDX-License-Identifier: GPL-2.0
2
3 bcachefs coding style
4 =====================
5
6 Good development is like gardening, and codeba
7 every day; look for little things that are out
8 A little weeding here and there goes a long wa
9 spiraled out of control.
10
11 Things don't always have to be perfect - nitpi
12 good. But appreciate beauty when you see it -
13
14 The code that you are afraid to touch is the c
15
16 A little organizing here and there goes a long
17
18 Put real thought into how you organize things.
19
20 Good code is readable code, where the structur
21 for bugs to hide.
22
23 Assertions are one of our most important tools
24 the course of writing a patchset you encounter
25 happen (and will have unpredictable or undefin
26 you're not sure if it can happen and not sure
27 BUG_ON(). Don't leave undefined or unspecified
28
29 By the time you finish the patchset, you shoul
30 assertions need to be handled and turned into
31 which should be logically impossible. Leave th
32 are logically impossible. (Or, make them debug
33 expensive - but don't turn everything into a d
34 we're not stuck debugging undefined behaviour
35 wrong).
36
37 Assertions are documentation that can't go out
38 wonderful.
39
40 Good assertions drastically and dramatically r
41 required to shake out bugs.
42
43 Good assertions are based on state, not logic.
44 have to think about what the invariants on you
45
46 Good invariants and assertions will hold every
47 means that you can run them in only a few plac
48 should you need to debug something that caused
49 quickly shotgun them everywhere to find the co
50
51 A good assertion checks something that the com
52 elide - if we were working in a language with
53 the compiler could check. This is something th
54 still be a few decades before it comes to syst
55 can still incorporate that kind of thinking in
56 invariants with runtime checks - much like the
57 dynamically typed languages may add type annot
58 code statically typed.
59
60 Looking for ways to make your assertions simpl
61 often nudge you towards making the entire syst
62
63 Good code is code where you can poke around an
64 introspection. We can't debug anything if we c
65
66 Whenever we're debugging, and the solution isn
67 issue is that we don't know where the issue is
68 going on - fix that first.
69
70 We have the tools to make anything visible at
71 percpu data structures among them. Don't let t
72
73 The most important tool for introspection is t
74 bcachefs, this means `*_to_text()` functions,
75
76 Pretty printers are wonderful, because they co
77 everywhere. Having functions to print whatever
78 make your error messages much easier to write
79 exist) and much more informative. And they can
80 well as tracepoints.
81
82 Runtime info and debugging tools should come w
83 labels, and good structure - we don't want fil
84 like in procfs. Part of the job of the debuggi
85 new developers as to how the system works.
86
87 Error messages should, whenever possible, tell
88 the issue. It's worth putting effort into them
89
90 Tracepoints shouldn't be the first thing you r
91 tool, but always look for more immediate ways
92 have to rely on tracing, we have to know which
93 and then we have to run the troublesome worklo
94 through logs. This is a lot of steps to go thr
95 something, and if it's intermittent it may not
96
97 The humble counter is an incredibly useful too
98 use, and many complicated internal operations
99 behave weirdly (anything involving memory recl
100 shockingly easy to debug once you have counter
101
102 Persistent counters are even better.
103
104 When debugging, try to get the most out of eve
105 rush to fix the initial issue. Look for things
106 easier the next time around - introspection, n
107 messages, new debug tools, and do those first.
108 better behaved; often one bug will uncover sev
109 downstream effects.
110
111 Fix all that first, and then the original bug
112 a user waiting. They'll thank you in the long
113 what you're doing you'll be amazed at how pati
114 like to help - otherwise they wouldn't be repo
115
116 Talk to your users. Don't isolate yourself.
117
118 Users notice all sorts of interesting things,
119 interacting with them you can benefit from the
120
121 Spend time doing support and helpdesk stuff. D
122 finished until it's being used trouble free.
123
124 This will also motivate you to make your debug
125 and perhaps even your documentation, too. Like
126 time you spend at it the better you'll get, an
127 person most able to improve the tools to make
128
129 Be wary of how you take on and commit to big p
130 become product-manager focused. Often time an
131 wait for its proper time - but you won't know
132 idea until you start writing code.
133
134 Expect to throw a lot of things away, or leave
135 Nobody writes all perfect code that all gets s
136 productive in the long run if you notice this
137 else. The experience gained and lessons learne
138 other work you do.
139
140 But don't be afraid to tackle projects that re
141 existing code. Sometimes these can be the best
142 us to make existing code more general, more fl
143 perhaps more robust. Just don't hesitate to ab
144 it's going to make a mess of things.
145
146 Complicated features can often be done as a se
147 final change that actually implements the feat
148 end. It's wonderful when this happens, especia
149 things that improve the codebase in their own
150 much less risk of wasted effort if the feature
151 out.
152
153 Always strive to work incrementally. Always st
154 into little bite sized projects that can prove
155
156 Instead of always tackling those big projects,
157 will be useful, and make the big projects easi
158
159 The question of what's likely to be useful is
160 often go astray - doing something because it s
161 leads to overengineering. Knowing what's usefu
162 experience, or talking with people who have th
163 reading lots of code and looking for common pa
164 afraid to throw things away and do something s
165
166 Talk about your ideas with your fellow develop
167 come from relaxed conversations where people a
168
169 Don't neglect your tools.
170
171 The most important tools (besides the compiler
172 tools we use for testing. The shortest possibl
173 essential for working productively. We learn,
174 errors in our thinking by running our code and
175 time is being wasted because your tools are ba
176 fix it.
177
178 Put effort into your documentation, commmit me
179 don't go overboard. A good commit message is w
180 was important enough to go in a commit message
181 even better as a code comment.
182
183 A good code comment is wonderful, but even bet
184 need to exist because the code was so straight
185 organized into small clean and tidy modules, w
186 for functions and variable, where every line o
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.