11# ThrowTheSwitch.org Coding Standard
2- Hi. Welcome to the coding standard for ThrowTheSwitch.org. For the most part,
3- we try to follow these standards to unify our contributors' code into a cohesive
4- unit (puns intended). You might find places where these standards aren't
2+
3+ Hi. Welcome to the coding standard for ThrowTheSwitch.org. For the most part,
4+ we try to follow these standards to unify our contributors' code into a cohesive
5+ unit (puns intended). You might find places where these standards aren't
56followed. We're not perfect. Please be polite where
6- you notice these discrepancies and we'll try to be polite when we notice yours.
7+ you notice these discrepancies and we'll try to be polite when we notice yours.
78;)
89
10+
911## Why Have A Coding Standard?
10- Being consistent makes code easier to understand. We've made an attempt to keep
11- our standard simple because we also believe that we can only expect someone to
12+
13+ Being consistent makes code easier to understand. We've made an attempt to keep
14+ our standard simple because we also believe that we can only expect someone to
1215follow something that is understandable. Please do your best.
1316
17+
1418## Our Philosophy
15- Before we get into details on syntax, let's take a moment to talk about our
16- vision for these tools. We're C developers and embedded software developers.
17- These tools are great to test any C code, but catering to embedded software has
18- made us more tolerant of compiler quirks. There are a LOT of quirky compilers
19- out there. By quirky I mean "doesn't follow standards because they feel like
19+
20+ Before we get into details on syntax, let's take a moment to talk about our
21+ vision for these tools. We're C developers and embedded software developers.
22+ These tools are great to test any C code, but catering to embedded software has
23+ made us more tolerant of compiler quirks. There are a LOT of quirky compilers
24+ out there. By quirky I mean "doesn't follow standards because they feel like
2025they have a license to do as they wish."
2126
22- Our philosophy is "support every compiler we can". Most often, this means that
23- we aim for writing C code that is standards compliant (often C89... that seems
24- to be a sweet spot that is almost always compatible). But it also means these
25- tools are tolerant of things that aren't common. Some that aren't even
26- compliant. There are configuration options to override the size of standard
27- types. There are configuration options to force Unity to not use certain
28- standard library functions. A lot of Unity is configurable and we have worked
27+ Our philosophy is "support every compiler we can". Most often, this means that
28+ we aim for writing C code that is standards compliant (often C89... that seems
29+ to be a sweet spot that is almost always compatible). But it also means these
30+ tools are tolerant of things that aren't common. Some that aren't even
31+ compliant. There are configuration options to override the size of standard
32+ types. There are configuration options to force Unity to not use certain
33+ standard library functions. A lot of Unity is configurable and we have worked
2934hard to make it not TOO ugly in the process.
3035
31- Similarly, our tools that parse C do their best. They aren't full C parsers
32- (yet) and, even if they were, they would still have to accept non-standard
33- additions like gcc extensions or specifying ` @0x1000 ` to force a variable to
34- compile to a particular location. It's just what we do, because we like
36+ Similarly, our tools that parse C do their best. They aren't full C parsers
37+ (yet) and, even if they were, they would still have to accept non-standard
38+ additions like gcc extensions or specifying ` @0x1000 ` to force a variable to
39+ compile to a particular location. It's just what we do, because we like
3540everything to Just Work™.
3641
37- Speaking of having things Just Work™, that's our second philosophy. By that, we
38- mean that we do our best to have EVERY configuration option have a logical
39- default. We believe that if you're working with a simple compiler and target,
40- you shouldn't need to configure very much... we try to make the tools guess as
42+ Speaking of having things Just Work™, that's our second philosophy. By that, we
43+ mean that we do our best to have EVERY configuration option have a logical
44+ default. We believe that if you're working with a simple compiler and target,
45+ you shouldn't need to configure very much... we try to make the tools guess as
4146much as they can, but give the user the power to override it when it's wrong.
4247
48+
4349## Naming Things
44- Let's talk about naming things. Programming is all about naming things. We name
45- files, functions, variables, and so much more. While we're not always going to
46- find the best name for something, we actually put quite a bit of effort into
50+
51+ Let's talk about naming things. Programming is all about naming things. We name
52+ files, functions, variables, and so much more. While we're not always going to
53+ find the best name for something, we actually put quite a bit of effort into
4754finding * What Something WANTS to be Called* ™.
4855
49- When naming things, we more or less follow this hierarchy, the first being the
56+ When naming things, we more or less follow this hierarchy, the first being the
5057most important to us (but we do all four whenever possible):
51581 . Readable
52592 . Descriptive
53603 . Consistent
54614 . Memorable
5562
63+
5664#### Readable
57- We want to read our code. This means we like names and flow that are more
58- naturally read. We try to avoid double negatives. We try to avoid cryptic
65+
66+ We want to read our code. This means we like names and flow that are more
67+ naturally read. We try to avoid double negatives. We try to avoid cryptic
5968abbreviations (sticking to ones we feel are common).
6069
70+
6171#### Descriptive
62- We like descriptive names for things, especially functions and variables.
63- Finding the right name for something is an important endeavor. You might notice
64- from poking around our code that this often results in names that are a little
65- longer than the average. Guilty. We're okay with a tiny bit more typing if it
72+
73+ We like descriptive names for things, especially functions and variables.
74+ Finding the right name for something is an important endeavor. You might notice
75+ from poking around our code that this often results in names that are a little
76+ longer than the average. Guilty. We're okay with a tiny bit more typing if it
6677means our code is easier to understand.
6778
68- There are two exceptions to this rule that we also stick to as religiously as
79+ There are two exceptions to this rule that we also stick to as religiously as
6980possible:
7081
71- First, while we realize hungarian notation (and similar systems for encoding
72- type information into variable names) is providing a more descriptive name, we
73- feel that (for the average developer) it takes away from readability and
82+ First, while we realize hungarian notation (and similar systems for encoding
83+ type information into variable names) is providing a more descriptive name, we
84+ feel that (for the average developer) it takes away from readability and
7485therefore is to be avoided.
7586
76- Second, loop counters and other local throw-away variables often have a purpose
77- which is obvious. There's no need, therefore, to get carried away with complex
78- naming. We find i, j, and k are better loop counters than loopCounterVar or
79- whatnot. We only break this rule when we see that more description could improve
87+ Second, loop counters and other local throw-away variables often have a purpose
88+ which is obvious. There's no need, therefore, to get carried away with complex
89+ naming. We find i, j, and k are better loop counters than loopCounterVar or
90+ whatnot. We only break this rule when we see that more description could improve
8091understanding of an algorithm.
8192
93+
8294#### Consistent
83- We like consistency, but we're not really obsessed with it. We try to name our
84- configuration macros in a consistent fashion... you'll notice a repeated use of
85- UNITY_EXCLUDE_BLAH or UNITY_USES_BLAH macros. This helps users avoid having to
86- remember each macro's details.
95+
96+ We like consistency, but we're not really obsessed with it. We try to name our
97+ configuration macros in a consistent fashion... you'll notice a repeated use of
98+ UNITY_EXCLUDE_BLAH or UNITY_USES_BLAH macros. This helps users avoid having to
99+ remember each macro's details.
100+
87101
88102#### Memorable
89- Where ever it doesn't violate the above principles, we try to apply memorable
90- names. Sometimes this means using something that is simply descriptive, but
91- often we strive for descriptive AND unique... we like quirky names that stand
92- out in our memory and are easier to search for. Take a look through the file
93- names in Ceedling and you'll get a good idea of what we are talking about here.
94- Why use preprocess when you can use preprocessinator? Or what better describes a
95- module in charge of invoking tasks during releases than release_invoker? Don't
96- get carried away. The names are still descriptive and fulfill the above
103+
104+ Where ever it doesn't violate the above principles, we try to apply memorable
105+ names. Sometimes this means using something that is simply descriptive, but
106+ often we strive for descriptive AND unique... we like quirky names that stand
107+ out in our memory and are easier to search for. Take a look through the file
108+ names in Ceedling and you'll get a good idea of what we are talking about here.
109+ Why use preprocess when you can use preprocessinator? Or what better describes a
110+ module in charge of invoking tasks during releases than release_invoker? Don't
111+ get carried away. The names are still descriptive and fulfill the above
97112requirements, but they don't feel stale.
98113
114+
99115## C and C++ Details
100- We don't really want to add to the style battles out there. Tabs or spaces?
101- How many spaces? Where do the braces go? These are age-old questions that will
102- never be answered... or at least not answered in a way that will make everyone
116+
117+ We don't really want to add to the style battles out there. Tabs or spaces?
118+ How many spaces? Where do the braces go? These are age-old questions that will
119+ never be answered... or at least not answered in a way that will make everyone
103120happy.
104121
105- We've decided on our own style preferences. If you'd like to contribute to these
106- projects (and we hope that you do), then we ask if you do your best to follow
122+ We've decided on our own style preferences. If you'd like to contribute to these
123+ projects (and we hope that you do), then we ask if you do your best to follow
107124the same. It will only hurt a little. We promise.
108125
126+
109127#### Whitespace
110- Our C-style is to use spaces and to use 4 of them per indent level. It's a nice
111- power-of-2 number that looks decent on a wide screen. We have no more reason
112- than that. We break that rule when we have lines that wrap (macros or function
113- arguments or whatnot). When that happens, we like to indent further to line
128+
129+ Our C-style is to use spaces and to use 4 of them per indent level. It's a nice
130+ power-of-2 number that looks decent on a wide screen. We have no more reason
131+ than that. We break that rule when we have lines that wrap (macros or function
132+ arguments or whatnot). When that happens, we like to indent further to line
114133things up in nice tidy columns.
115134
116135``` C
@@ -120,17 +139,21 @@ things up in nice tidy columns.
120139 }
121140```
122141
142+
123143#### Case
144+
124145- Files - all lower case with underscores.
125146- Variables - all lower case with underscores
126147- Macros - all caps with underscores.
127148- Typedefs - all caps with underscores. (also ends with _T).
128149- Functions - camel cased. Usually named ModuleName_FuncName
129150- Constants and Globals - camel cased.
130151
152+
131153#### Braces
132- The left brace is on the next line after the declaration. The right brace is
133- directly below that. Everything in between in indented one level. If you're
154+
155+ The left brace is on the next line after the declaration. The right brace is
156+ directly below that. Everything in between in indented one level. If you're
134157catching an error and you have a one-line, go ahead and to it on the same line.
135158
136159```C
@@ -139,32 +162,42 @@ catching an error and you have a one-line, go ahead and to it on the same line.
139162 //Like so. Even if only one line, we use braces.
140163 }
141164```
142-
165+
166+
143167#### Comments
144- Do you know what we hate? Old-school C block comments. BUT, we're using them
145- anyway. As we mentioned, our goal is to support every compiler we can,
146- especially embedded compilers. There are STILL C compilers out there that only
147- support old-school block comments. So that is what we're using. We apologize. We
168+
169+ Do you know what we hate? Old-school C block comments. BUT, we're using them
170+ anyway. As we mentioned, our goal is to support every compiler we can,
171+ especially embedded compilers. There are STILL C compilers out there that only
172+ support old-school block comments. So that is what we're using. We apologize. We
148173think they are ugly too.
149174
175+
150176## Ruby Details
151- Is there really such thing as a Ruby coding standard? Ruby is such a free form
152- language, it seems almost sacrilegious to suggest that people should comply to
177+
178+ Is there really such thing as a Ruby coding standard? Ruby is such a free form
179+ language, it seems almost sacrilegious to suggest that people should comply to
153180one method! We'll keep it really brief!
154181
182+
155183#### Whitespace
156- Our Ruby style is to use spaces and to use 2 of them per indent level. It's a
157- nice power-of-2 number that really grooves with Ruby's compact style. We have no
158- more reason than that. We break that rule when we have lines that wrap. When
184+
185+ Our Ruby style is to use spaces and to use 2 of them per indent level. It's a
186+ nice power-of-2 number that really grooves with Ruby's compact style. We have no
187+ more reason than that. We break that rule when we have lines that wrap. When
159188that happens, we like to indent further to line things up in nice tidy columns.
160189
190+
161191#### Case
192+
162193- Files - all lower case with underscores.
163194- Variables - all lower case with underscores
164195- Classes, Modules, etc - Camel cased.
165196- Functions - all lower case with underscores
166197- Constants - all upper case with underscores
167198
199+
168200## Documentation
169- Egad. Really? We use markdown and we like pdf files because they can be made to
201+
202+ Egad. Really? We use markdown and we like pdf files because they can be made to
170203look nice while still being portable. Good enough?
0 commit comments