filesystems/bcachefs/CodingStyle.rst

1 .. SPDX-License-Identifier: GPL-2.0
11 Things don't always have to be perfect - nitpicking often does more harm than
12 good. But appreciate beauty when you see it - and let people know.
14 The code that you are afraid to touch is the code most in need of refactoring.
20 Good code is readable code, where the structure is simple and leaves nowhere
24 the course of writing a patchset you encounter a condition that shouldn't
26 you're not sure if it can happen and not sure how to handle it yet - make it a
27 BUG_ON(). Don't leave undefined or unspecified behavior lurking in the codebase.
29 By the time you finish the patchset, you should understand better which
31 which should be logically impossible. Leave the BUG_ON()s in for the ones which
33 expensive - but don't turn everything into a debug mode assertion, so that
37 Assertions are documentation that can't go out of date. Good assertions are
40 Good assertions drastically and dramatically reduce the amount of testing
43 Good assertions are based on state, not logic. To write good assertions, you
44 have to think about what the invariants on your state are.
47 means that you can run them in only a few places in the checked in version, but
48 should you need to debug something that caused the assertion to fail, you can
49 quickly shotgun them everywhere to find the codepath that broke the invariant.
51 A good assertion checks something that the compiler could check for us, and
52 elide - if we were working in a language with embedded correctness proofs that
53 the compiler could check. This is something that exists today, but it'll likely
55 can still incorporate that kind of thinking into our code and document the
56 invariants with runtime checks - much like the way people working in
60 Looking for ways to make your assertions simpler - and higher level - will
61 often nudge you towards making the entire system simpler and more robust.
63 Good code is code where you can poke around and see what it's doing -
64 introspection. We can't debug anything if we can't see what's going on.
66 Whenever we're debugging, and the solution isn't immediately obvious, if the
67 issue is that we don't know where the issue is because we can't see what's
68 going on - fix that first.
70 We have the tools to make anything visible at runtime, efficiently - RCU and
73 The most important tool for introspection is the humble pretty printer - in
83 labels, and good structure - we don't want files with a list of bare integers,
84 like in procfs. Part of the job of the debugging tools is to educate users and
85 new developers as to how the system works.
88 the issue. It's worth putting effort into them.
90 Tracepoints shouldn't be the first thing you reach for. They're an important
92 have to rely on tracing, we have to know which tracepoints we're looking for,
93 and then we have to run the troublesome workload, and then we have to sift
94 through logs. This is a lot of steps to go through when a user is hitting
97 The humble counter is an incredibly useful tool. They're cheap and simple to
100 shockingly easy to debug once you have counters on every distinct codepath.
104 When debugging, try to get the most out of every bug you come across; don't
105 rush to fix the initial issue. Look for things that will make related bugs
106 easier the next time around - introspection, new assertions, better error
107 messages, new debug tools, and do those first. Look for ways to make the system
111 Fix all that first, and then the original bug last - even if that means keeping
112 a user waiting. They'll thank you in the long run, and when they understand
114 like to help - otherwise they wouldn't be reporting the bug in the first place.
121 Spend time doing support and helpdesk stuff. Don't just write code - code isn't
125 and perhaps even your documentation, too. Like anything else in life, the more
126 time you spend at it the better you'll get, and you the developer are the
127 person most able to improve the tools to make debugging quick and easy.
129 Be wary of how you take on and commit to big projects. Don't let development
130 become product-manager focused. Often time an idea is a good one but needs to
131 wait for its proper time - but you won't know if it's the proper time for an
136 productive in the long run if you notice this early and shift to something
137 else. The experience gained and lessons learned will be valuable for all the
141 existing code. Sometimes these can be the best projects, because they can lead
143 perhaps more robust. Just don't hesitate to abandon the idea if it looks like
146 Complicated features can often be done as a series of refactorings, with the
147 final change that actually implements the feature as a quite small patch at the
149 things that improve the codebase in their own right. When that happens there's
150 much less risk of wasted effort if the feature you were going for doesn't work
153 Always strive to work incrementally. Always strive to turn the big projects
157 will be useful, and make the big projects easier.
159 The question of what's likely to be useful is where junior developers most
160 often go astray - doing something because it seems like it'll be useful often
162 experience, or talking with people who have that experience - or from simply
166 Talk about your ideas with your fellow developers; often times the best things
171 The most important tools (besides the compiler and our text editor) are the
172 tools we use for testing. The shortest possible edit/test/debug cycle is
173 essential for working productively. We learn, gain experience, and discover the
175 time is being wasted because your tools are bad or too slow - don't accept it,
178 Put effort into your documentation, commit messages, and code comments - but
179 don't go overboard. A good commit message is wonderful - but if the information
180 was important enough to go in a commit message, ask yourself if it would be
183 A good code comment is wonderful, but even better is the comment that didn't
184 need to exist because the code was so straightforward as to be obvious;