Commit | Line | Data |
---|---|---|
cbed66ad | 1 | Notes on coding style |
1528431b | 2 | |
cbed66ad MW |
3 | * General |
4 | ||
5 | ** Layout | |
6 | ||
7 | Lines are 77 characters at most, except for strange special effects. | |
8 | Don't ask. This is not negotiable, though. Don't try to tell me that | |
9 | your monitor is very wide so you can read longer lines. My monitor is | |
10 | likely at least as wide. On the other hand, most lines are easily short | |
11 | enough to fit in my narrow columns, so the right hand side of a wide | |
12 | window would be mostly blank. This seems wasteful to me, when I could | |
13 | fill that space with more code. | |
14 | ||
15 | Horizontal whitespace for layout purposes -- i.e., indentation and | |
16 | alignment, rather than just separating words -- consists of as many tabs | |
17 | as possible, followed by as many spaces as necessary to reach the target | |
18 | column. Tab stops occur at every eight columns. You can tell this | |
19 | because when you cat a file to your terminal, that's how the tabs | |
20 | appear. Editors which disagree about this are simply wrong. | |
21 | ||
22 | My indentation quantum is usually two columns. It seems that some | |
23 | modern editors are deeply confused, and think that tab width and | |
24 | indentation quantum are the same thing, but they aren't. Such broken | |
25 | editors will make a hopeless mess of my code. If you have the | |
26 | misfortune to use such an editor, maybe you could contribute patches to | |
27 | fix it. | |
28 | ||
29 | ||
30 | * Lisp style | |
31 | ||
32 | ** Language subset and extensions | |
1528431b MW |
33 | |
34 | None of ANSI Common Lisp is off-limits. | |
35 | ||
828cb3b1 MW |
36 | I think my Lisp style is rather more imperative in flavour than most |
37 | modern Lisp programmers. It's probably closer to historical Lisp | |
a1b51e19 MW |
38 | practice in that regard, even though I wasn't writing Lisp back then. A |
39 | lot of this is because I don't assume that the Lisp implementation | |
40 | handles tail calls properly: Common Lisp is not Scheme. | |
828cb3b1 | 41 | |
1528431b MW |
42 | I make extensive use of CLOS, and macros. On a couple of occasions I've |
43 | made macros which use CLOS generic function dispatch to compute their | |
44 | expansions. The parser language is probably the best example of this in | |
828cb3b1 MW |
45 | the codebase. |
46 | ||
a1b51e19 MW |
47 | I like hairy ~format~ strings. I've intentionally opted to leave them |
48 | as challenges to the reader rather than explain them. | |
1528431b MW |
49 | |
50 | I've avoided hairy ~loop~ for the most part, not because I dislike it | |
51 | strongly but because others do and I don't find that it wins big enough | |
52 | for the fight to be worthwhile. | |
53 | ||
54 | I only use ~&aux~ lambda-list parameters in ~defstruct~ BOA | |
55 | constructors, for special effects. | |
56 | ||
57 | I use ~car~, not ~first~, and ~cdr~, not ~rest~. Similarly, I use | |
58 | ~cadr~, not ~second~, and I'm not afraid to use ~cddr~ or ~cadar~. | |
59 | ||
60 | Similarly, I've not used ~elt~, preferring to know what kind of sequence | |
61 | I'm dealing with, or using the built-in sequence functions. | |
62 | ||
63 | I'm happy to use ~1+~, and I like the brevity of ~1-~ enough to use it | |
64 | despite its terrible name. | |
65 | ||
66 | There are no reader syntax extensions in the code. This is because I | |
67 | couldn't think of any way they'd be especially helpful, and not because | |
68 | I'm in any way opposed to them. | |
69 | ||
70 | The main translator, in the ~SOD~ package, tries to assume very little | |
71 | beyond ANSI Common Lisp and what's included in just about every serious | |
72 | implementation: specifically, MOP introspection, and Gray streams. | |
73 | There's intentionally no MOP intercession. | |
74 | ||
7e55d099 MW |
75 | The frontend additionally makes use of ~cl-launch~, but the dependency |
76 | is actually quite weak, and it could be replaced with a different, maybe | |
1528431b MW |
77 | implementation-specific, mechanism fairly easily. I'm keen to take |
78 | patches which improve frontend portability. | |
79 | ||
80 | I'm more tolerant of extensions and external dependencies in the test | |
81 | suite, which makes additional use of ~xlunit~. Running the test suite | |
82 | isn't essential to getting the translator built, so this isn't as much | |
83 | of a problem. | |
84 | ||
cbed66ad | 85 | ** Layout |
1528431b MW |
86 | |
87 | I pretty much let Emacs indent my code for me, based on information | |
88 | collected by SLIME. Some exceptions: | |
89 | ||
90 | + DSLs (e.g., the parser language) have their own space of macros | |
91 | which Emacs doesn't understand and for the most part I haven't | |
92 | bothered to teach it. | |
93 | ||
94 | + Emacs sometimes does a bad job with hairy ~loop~ and requires manual | |
95 | fixing. Since I don't use hairy ~loop~ much, this isn't a major | |
96 | problem. | |
97 | ||
f458e64e MW |
98 | + Emacs indents lambda lists really badly. I often prefer to put the |
99 | entire lambda list on its own line than to split it. If I have to | |
100 | split a simple lambda list, without lambda-list keywords, I just | |
101 | align the start of each subsequent line with the start of the first | |
102 | argument. I break hairy lambda lists before lambda-list keywords, | |
103 | and the start of a subsequent line aligns with the first argument | |
104 | name following the lambda-list keyword which begins the group, so | |
105 | that the lambda-list keyword stands out. | |
106 | ||
107 | : (defun many-arguments (first second third | |
108 | : fourth fifth) | |
109 | : ...) | |
110 | ||
111 | : (defun hairy-arguments (first second third | |
112 | : &optional fourth fifth | |
113 | : sixth | |
114 | : &rest others) | |
115 | : ...) | |
116 | ||
117 | I don't know what I'd do if I had a hairy lambda list with so many | |
118 | mandatory positional arguments that I had to split them. So far, | |
119 | this situation hasn't come up. | |
120 | ||
1528431b MW |
121 | Lisp code does have a tendency to march across to the right quite |
122 | rapidly given a chance. I have a number of strategies for dealing with | |
123 | this. | |
124 | ||
125 | + Break a long nested calculation into pieces, giving names to the | |
126 | intermediate results, in a ~let*~ form. | |
127 | ||
7e55d099 MW |
128 | + Hoist deeply nested complex computations out into ~flet~ or |
129 | ~labels~, and then invoke them from inside whatever complicated | |
1528431b MW |
130 | conditional mess was needed to decide what to do. |
131 | ||
132 | + Shrug my shoulders and let code dribble down the right hand side for | |
133 | a bit. | |
134 | ||
cbed66ad | 135 | ** Packages and exporting |
1528431b MW |
136 | |
137 | A package collects symbols which are given meanings in one or more | |
138 | source files. If a package's code is all in one file, then the package | |
139 | definition can be put in that file too; otherwise I put it in its own | |
140 | file. | |
141 | ||
142 | I don't put ~:export~ in package definitions. Instead, I scatter calls | |
143 | to the ~export~ function throughout the code, right next to where the | |
144 | relevant symbol is defined. This has three important advantages. | |
145 | ||
146 | + You can tell, when you're reading the code which defines ~foo~, | |
147 | whether ~foo~ is exported and therefore a defined part of the | |
148 | package interface. | |
149 | ||
150 | + When you know that you're writing a thing which will form part of | |
151 | the package interface, you don't have to go off and edit some other | |
152 | file to export it. | |
153 | ||
154 | + A master list of exported symbols becomes a merge hazard: if two | |
155 | different branches add symbols to nearby pieces of the master list | |
156 | then you get a merge conflict for no especially good reason. | |
157 | ||
158 | There's an apparent disadvantage: there's no immediately visible master | |
159 | list of exported symbols. But that's not a big problem: | |
160 | ||
161 | : (loop for s being the external-symbols of pkg collect s) | |
162 | ||
163 | See ~doc/list-symbols.lisp~ for more sophisticated reporting. (In | |
164 | particular, this identifies what kind of thing(s) each external symbol | |
165 | names.) | |
166 | ||
cbed66ad | 167 | ** Comments and file structuring |
1528431b MW |
168 | |
169 | A file starts with a big ~;;;~ comment bearing the Emacs ~-*-lisp-*-~ | |
170 | marker, a quick description, and copyright and licensing boilerplate. I | |
171 | don't use four-semicolon comments, and I only use ~#|~ ... ~|#~ for | |
172 | special effects. | |
173 | ||
174 | Then there's package stuff. There may be a ~cl:defpackage~ form (with | |
175 | explicit package qualifier) if the relevant package doesn't have its own | |
a1b51e19 MW |
176 | package definition file. I use gensyms to name packages: strings don't |
177 | seem right, and symbols would leak into some unrelated package. | |
1528431b MW |
178 | |
179 | Then there's ~cl:in-package~. Like ~defpackage~, I use a gensym to name | |
180 | the package. I can't think offhand of a good reason to have a file with | |
7e55d099 MW |
181 | sections `in' more than one package. So, the ~in-package~ form goes at |
182 | the top of the file, before the first section header. If sections are | |
183 | going to end up in separate packages, I think I'd put a ~cl:in-package~ | |
184 | at the top of each section in case I wanted to reorder them. | |
1528431b MW |
185 | |
186 | The rest of the file consists of Lisp code. I don't use page boundaries | |
187 | ~^L~ to split files up. Instead, I use big banner comments for this: | |
188 | ||
189 | : ;;;-------------------------------------------------------------------------- | |
190 | : ;;; Section title. | |
191 | ||
192 | Sections don't usually have internal comments, but if they did they'd | |
193 | also be ~;;;~ comments. | |
194 | ||
195 | Almost all definitions get documentation strings. I've tried to be | |
196 | consistent about formatting. | |
197 | ||
198 | + Docstring lines are 77 characters or less. | |
199 | ||
200 | + The first line gives a summary of what the thing does. The summary, | |
201 | together with the SLIME-generated synopsis, is likely enough to | |
202 | remind you what the thing does. | |
203 | ||
204 | + The rest of the lines are indented by three spaces, and explain | |
205 | carefully what the thing does and what all the parameters mean. | |
206 | ||
207 | Smallish functions and macros don't usually need any further | |
208 | commentary. Big functions often need to be split into bitesize pieces | |
209 | with their own internal ~;;~ comments. The idea is that these comments | |
210 | should explain the code's overall strategy to the reader, and help them | |
211 | figure out how a piece fits into that strategy. | |
212 | ||
213 | Winged, single ~;~ comments are very rare. | |
214 | ||
215 | Files end, as a result of long tradition, with a comment | |
216 | ||
217 | : ;;;----- That's all, folks -------------------------------------------------- | |
218 | ||
cbed66ad | 219 | ** Macro style |
1528431b MW |
220 | |
221 | I don't mind complicated macros if they're doing something worthwhile. | |
222 | They need to have good documentation strings, though. | |
223 | ||
224 | That said, where possible I've tried to factor macros into an actual | |
225 | macro providing the syntactic sugar, and a function which receives the | |
226 | parameters and $\eta$-expanded forms, and does the actual work. | |
227 | ||
228 | It's extremely bad taste for a macro to evaluate its evaluable | |
229 | parameters in any order other than strictly left to right, or to | |
230 | evaluate them more than once. | |
231 | ||
cbed66ad | 232 | ** Data structures |
1528431b MW |
233 | |
234 | I've tended to be happy with plain lists for homogeneous-ish | |
235 | collections. Strongly heterogeneous collections (other than input | |
236 | syntax, destructured using ~defmacro~ or ~destructuring-bind~) I've | |
237 | tended to make a proper data type for. | |
238 | ||
239 | My first instinct when defining a new structure is to use ~defclass~. | |
240 | While it's annoyingly verbose, it has the immense benefit over | |
241 | ~defstruct~ that it's safe to redefine CLOS classes in a running image | |
242 | without the world breaking, and I usually find it necessary to add or | |
243 | change slots while I'm working on new code. Once a piece of code has | |
244 | settled down and I have a good feel for what my structure is actually | |
245 | doing, I might switch the ~defclass~ for a ~defstruct~. Several | |
246 | questions influence my decision. | |
247 | ||
248 | + Do slot accesses need to be really fast? My usual Lisp | |
249 | implementations aggressively optimize ~defstruct~ accessor | |
250 | functions. | |
251 | ||
7e55d099 | 252 | + Have I subclassed my class? While I can move over a |
1528431b MW |
253 | single-inheritance tree using ~:include~, it seems wrong to do this |
254 | most of the time. Also, I'd be precluding subclasses from multiple | |
255 | inheritance, and I'd either have to prohibit subclassing by | |
256 | extensions or have to commit to ~defstruct~ in the documentation. | |
257 | In general, I'm much happier committing to ~defclass~. | |
258 | ||
259 | + Are there methods specialized on my class? Again, structure classes | |
260 | make fine method specializers, but it doesn't seem right. | |
261 | ||
262 | Apart from being hard to redefine, ~defstruct~ does a pretty good job of | |
263 | making a new structure type. I tend to tidy up a few rough edges. | |
264 | ||
265 | + The default predicate always has ~-p~ appended. If the class name | |
266 | is a single word, then I'll explicitly name the predicate with a | |
267 | simple ~p~ suffix. For example, ~ship~ would have the predicate | |
a51bf71a | 268 | ~shipp~, rather than ~ship-p~. |
1528431b MW |
269 | |
270 | + If there are slots I can't default then I'll usually provide a BOA | |
271 | constructor which sets them from required parameters; other slots | |
272 | I'll set from optional or keyword parameters according to my taste | |
273 | and judgement. | |
274 | ||
275 | + Slots mustn't be given names which are external in any package. | |
276 | Unfortunately, slot names are used in constructing accessor names, | |
277 | and sometimes the right accessor name involves a prohibited symbol. | |
278 | I've mostly addressed this by naming the slot ~%foo~, and then | |
279 | providing inline reader and writer functions. (CLOS class | |
280 | definitions don't have this problem because you get to set the | |
281 | accessor function names independently of the slot names.) | |
282 | ||
283 | + BOA constructors are strange. You can set the initial slots based | |
284 | on an arbitrary computation on the provided parameters, but you have | |
285 | to roll up your sleeves and mess with ~&aux~ parameters to pull it | |
286 | off. | |
287 | ||
cbed66ad | 288 | ** Naming |
1528431b MW |
289 | |
290 | I'm a traditionalist in some ways, and one of the reasons I like Lisp is | |
291 | the richness of its history and tradition. | |
292 | ||
293 | In other languages, I tend to use single- or two-letter names for | |
294 | variables and structure slots; not so much in Lisp. Other languages | |
295 | express more using punctuation, so the names stand out easily; I find | |
296 | that short names can be lost more easily in Lisp. | |
297 | ||
298 | I've also tended to go for fairly prosaic names, taking my inspiration | |
299 | from the CLOS MOP. While I mourn the loss of whimsical names like | |
300 | ~haulong~ and ~haipart~, I've tried to avoid inventing more of them. | |
301 | ||
f458e64e MW |
302 | There's a convention, which I think comes from ML, of using ~_~ where a |
303 | binding occurrence of a variable name is expected, to signify that that | |
304 | the corresponding value is to be discarded. Common Lisp, alas, doesn't | |
305 | have such a convention. Instead, there's a sequence of silly names used | |
306 | with the same intention, and the bindings are then explicitly ignored | |
307 | with a declaration. The names begin ~hunoz~, ~hukairz~, and (I think) | |
308 | ~huaskt~. | |
1528431b | 309 | |
cbed66ad | 310 | ** Declarations |
1528431b MW |
311 | |
312 | The code is light on declarations, other than ~ignore~ and similar used | |
313 | to muffle warnings. The macros try to do sensible things with | |
314 | declarations, and I think they succeed fairly well, but there might be | |
315 | bugs and rough edges. I know that some are just broken because, for | |
316 | actual correctness, declarations provided by the caller need to be split | |
317 | up into a number of different parts of the expansion, which in turn | |
318 | requires figuring out what the declarations mean and which bindings | |
319 | they're referring to. That's not completely impossible, assuming that | |
f458e64e | 320 | there aren't implementation-specific declarations with crazy syntax |
1528431b MW |
321 | mixed in there, but it's more work than seems worthwhile. |
322 | ||
323 | ||
82892195 MW |
324 | * C style |
325 | ||
326 | ** Language subset and extensions | |
327 | ||
328 | I'm trying to support C89 still. There are few really worthwhile | |
329 | features in C99 and later, though there are some. For now, I want Sod | |
330 | to continue working if built with a C89 compiler, even if some things -- | |
331 | e.g., most notably the macro sugar for varargs messages -- are | |
332 | unavailable. | |
333 | ||
334 | Similarly, I'll use compiler-specific features if they don't adversely | |
335 | affect portability. For example, I'll use GCC attributes to improve | |
336 | compiler diagnostics, but they're wrapped up in preprocessor hacking so | |
337 | that they won't be noticed by compilers which don't understand them. | |
338 | I'm generally happy to accept contributions which make similar | |
339 | improvements for other compilers. | |
340 | ||
341 | Sod is supposed to have minimal dependencies. It should be able to work | |
342 | in what the ISO C standard names a `freestanding environment', without | |
343 | most of the standard C library. The keyword-argument library is | |
344 | carefully split into a piece which is fully portable and a piece which | |
345 | depends on features which are only available in hosted environments, | |
346 | like being able to print stuff to ~stderr~, so that users targetting | |
347 | embedded systems have an easy porting job. | |
348 | ||
349 | ** Naming | |
350 | ||
351 | I usually give local variables, arguments, and structure members very | |
352 | short names, just one or two characters long. I find that longer names | |
353 | are harder to distinguish, and take up horizontal space. Besides, | |
354 | mathematicians have been using single-letter variable names quite | |
355 | successfully for hundreds of years. | |
356 | ||
357 | I usually choose variable names to match their types in an informal way. | |
358 | Loop counters are often called ~i~, ~j~, ~k~; generic pointers, and | |
359 | pointers to bytes or characters, are usually ~p~ or ~q~; a character is | |
360 | often ~ch~; a ~FILE~ pointer is ~fp~ following long tradition; sizes of | |
361 | things, in bytes, are ~sz~, while lengths of vectors, in elements, are | |
362 | ~n~. I often name values of, or pointers to, structures or custom types | |
363 | with the first letter of the type. If I have two things of the same | |
364 | kind, I'll often double the name of one of them; e.g., if I have two | |
365 | pointers to ~whatsit~ structures, I might call them ~w~ and ~ww~. | |
366 | ||
367 | I don't (any more) give ~typedef~ names to structures or unions. This | |
368 | makes it possible to have a variable with the same name as the structure | |
369 | tag without serious trouble. | |
370 | ||
371 | In variable names, I tend to just squash pieces of words together; in | |
372 | longer names, sometimes I'll put in underscores to split things up a | |
373 | bit. Camel case is bletcherous. | |
374 | ||
375 | File-scope names with /internal/ linkage -- i.e., things marked ~static~ | |
376 | -- generally deserve somewhat longer names. I don't give them other | |
377 | kind of marking; e.g., I'd probably name the pointer to the head of a | |
378 | list of ~foo~ things something like ~foohead~. | |
379 | ||
380 | Names with /external/ linkage want more care because they're playing in | |
381 | a shared global namespace. | |
382 | ||
383 | ** Layout | |
384 | ||
385 | The C indent quantum is two columns. | |
386 | ||
387 | Declarations go at the top of functions. I don't put declarations in | |
388 | inner blocks, and I certainly don't scatter declarations throughout a | |
389 | block. I find that having the declarations all in one place makes it | |
390 | easier for me to keep track of what things the function is going to be | |
391 | thinking about. | |
392 | ||
393 | If I can't set a variable to its proper value immediately, I'll leave it | |
394 | uninitialized until I can. That way, the compiler will warn me if I | |
395 | forget. | |
396 | ||
397 | Most of my style is an attempt to get as much interesting code on the | |
398 | screen at a time, and still be able to read it. The short variable | |
399 | names keep things distinct while keeping statements short; short | |
400 | statements don't need to be split across multiple lines. And keeping | |
401 | the overall line length limit low means I can fit more /columns/ of code | |
402 | on my screen. | |
403 | ||
404 | If there are several related variables with the same declaration | |
405 | specifiers, I'll usually write a single declaration for all of them -- | |
406 | even if they have different actual types. For example, | |
407 | ||
408 | : struct foo f, *fp = &f; | |
409 | ||
410 | Note that a ~*~ declarator operator has a space to its left, but never | |
411 | to its right. (Stroustrup's style horribly misrepresents the underlying | |
412 | syntax.) | |
413 | ||
414 | I will often write multiple statements on a single line, usually to | |
415 | indicate that these things are part of the same thought, and they | |
416 | shouldn't be separated. For example, if I'm working through an array of | |
417 | things, I might have a pointer ~p~ to the element I'm hacking on, and a | |
418 | count ~n~ of things left to hack, I'll have a loop | |
419 | ||
420 | : while (n) { | |
421 | : /* hack on *p */ | |
422 | : p++; n--; | |
423 | : } | |
424 | ||
425 | so that the two updates don't get separated. | |
426 | ||
427 | I don't wrap braces around individual statements that fit on a single | |
428 | line. For example, I'll write | |
429 | ||
430 | : while (*p == ' ') p++; | |
431 | ||
432 | On the other hand, if a single substatement is going to take more than | |
433 | one line then it gets wrapped in braces. | |
434 | ||
435 | I don't write blocks which aren't part of larger compound statements, | |
436 | e.g., ~if~ or ~while~. I'll write a compound statementon a single line | |
437 | if I can; but I'll split ~if~ with an ~else~ over two lines. For | |
438 | example, | |
439 | ||
440 | : if (a == 1) x = 0; | |
441 | : else if (b == 3) { y = 2; z = 1; } | |
442 | : else w = 15; | |
443 | ||
444 | On the other hand, if I can't write all of the branches of an | |
445 | ~if~\relax/\relax ~else if~ ladder like this, then /all/ of the | |
446 | substatements get their own lines. (I write ~do~\relax/\relax ~while~ | |
447 | loops in the same way, but this comes up much less frequently.) | |
448 | ||
449 | If I can't write a block on the same line, then the opening brace goes | |
450 | on the same line as the statement head, and the closing brace gets its | |
451 | own line. A trailing ~else~ or ~while~ goes on the same line as the | |
452 | previous closing brace, if there is one. | |
453 | ||
454 | I don't write spaces inside parentheses or square brackets, or between | |
455 | unary operators and their operands. I always write ~sizeof~ as if it | |
456 | were a function, even though I know it isn't. I write a single space | |
457 | either side of non-multiplicative binary operators -- i.e., other than | |
458 | ~*~, ~/~, ~%~, and ~&~; I don't write spaces around multiplicative | |
459 | operators any more. The comma operator is special, and gets a space | |
460 | after, but not before. | |
461 | ||
462 | If I'm breaking a long line at a binary operator, the break comes | |
463 | /after/ the operator, not before. | |
464 | ||
465 | ** Common conventions | |
466 | ||
467 | A /predicate/ is a function which answers a yes/no question -- and has | |
468 | no side-effects. I don't use ~bool~ or similar; predicates return | |
469 | ~int~, such that zero is false and nonzero is true. Predicates usually | |
470 | have names ending in ~p~ or ~_p~. (Note that function names | |
471 | beginning ~is...~ are reserved for future ~<ctype.h>~ macros.) | |
472 | ||
473 | On the other hand, an /operation/ is a function whose main purpose is to | |
474 | have an effect -- maybe create a thing, or update some state. In the | |
475 | absence of better ideas, operations also return ~int~, but zero | |
476 | indicates success, and nonzero -- usually $-1$ -- indicates failure. | |
477 | ||
478 | ** Error handling and resource management | |
479 | ||
480 | I've tried many techniques. I think the following is the best approach | |
481 | so far. | |
482 | ||
483 | I try to arrange that every type which represents some resource which | |
484 | might need releasing has an easily recognizable `inert' value which | |
485 | indicates that the resource has not been acquired. At the top of a | |
486 | function, I initialize all of the variables which might hold onto | |
487 | resources to their inert values. At the end of the function, I place a | |
488 | label, ~end~ or ~fail~. An ~end~ label is for common cleanup; a ~fail~ | |
489 | label is for cleanup that's only needed on unsuccessful completion. | |
490 | ||
491 | ||
492 | ** Miscellaneous style issues | |
493 | ||
494 | I write ~0~, not ~NULL~. Doing this prevents a common error in | |
495 | null-terminated variable-length argument lists, e.g., ~execlp~, where | |
496 | ~NULL~ is actually an integer ~0~ in disguise and ends up being an ~int~ | |
497 | where a pointer was wanted. | |
498 | ||
499 | I don't usually write redundant comparisons against ~0~, or ~NULL~, or | |
500 | well-known return codes indicating success. Again, this helps with | |
501 | compression. I'll write | |
502 | ||
503 | : rc = do_something(foo, bar); if (rc) goto end; | |
504 | ||
505 | (yes, one line) rather than comparing ~rc~ against some ~STATUS_SUCCESS~ | |
506 | code or similar. Exception: I still haven't decided whether I prefer | |
507 | leaving the explicit relational in ~strcmp~ and similar tests. | |
508 | ||
509 | I always write parentheses around the expression in a ~return~ | |
510 | statement. | |
511 | ||
512 | In declarations, storage classes come first (e.g., ~static~, ~extern~, | |
513 | ~typedef~), followed by qualifiers (~const~, ~volatile~; I never use | |
514 | ~restrict~), and then the type specifiers, signedness indicators first | |
515 | where they aren't redundant (so maybe ~signed char~ for special effects, | |
516 | but never ~signed int~), then length indicators, then the base type. I | |
517 | omit ~int~ if there are other type specifiers, so ~unsigned~ or ~long~, | |
518 | rather than ~unsigned int~ or ~long int~. | |
519 | ||
520 | The full declarator syntax for function pointer is pretty ugly. I often | |
521 | simplify it by defining a ~typedef~ for the /function/ type, not the | |
522 | function pointer type. For example | |
523 | ||
524 | : typedef int callbackfn(struct thing */*t*/, void */*p*/); | |
525 | ||
526 | I'd then use variables (structure members, arguments, etc.) of type | |
527 | ~callbackfn *~. | |
528 | ||
529 | In header files, I comment out argument names to prevent problems with | |
530 | macros defined by client translation units. Also, I explicitly mark | |
531 | function declarations as being ~extern~. | |
532 | ||
533 | ** Comments and file structuring | |
534 | ||
535 | I never use C++-style ~//~ comments except for temporary special | |
536 | effects. | |
537 | ||
538 | If a comment fits on one line, then its closing ~*/~ is on the same | |
539 | line; otherwise, the ending ~*/~ is on a line by itself, and there's a | |
540 | spine of ~*~ characters in a column on the left. | |
541 | ||
542 | A file starts with a big comment bearing the Emacs ~-*-c-*-~ marker, a | |
543 | quick description, and copyright and licensing boilerplate. | |
544 | ||
545 | Header files are wrapped up with multiple-inclusion and C++ guards, with | |
546 | ||
547 | : #ifndef HEADER_H | |
548 | : #define HEADER_H | |
549 | : | |
550 | : #ifdef __cplusplus | |
551 | : extern "C" { | |
552 | : #endif | |
553 | ||
554 | at the top. | |
555 | ||
556 | The rest of the file consists of C code. I don't use page boundaries | |
557 | ~^L~ to split files up. Instead, I use big banner comments for this: | |
558 | ||
559 | : /*----- Section title -----------------------------------------------------*/ | |
560 | ||
561 | Following long tradition, functions and macros are documented in a | |
562 | preceding comment which looks like this. | |
563 | ||
564 | : /* --- @name@ --- * | |
565 | : * | |
566 | : * Arguments: @type fmm@ = a five-minute argument | |
567 | : * @type fhh@ = the full half-hour | |
568 | : * | |
569 | : * Returns: A return value. | |
570 | : * | |
571 | : * Use: It does a thing. Otherwise I wouldn't have bothered. | |
572 | : */ | |
573 | ||
574 | Sometimes (rarely) the description of the return value explains | |
575 | sufficiently what the thing does. If so, the `Use' part can be omitted. | |
576 | Fragments of C code in this comment are surrounded by ~@~ characters. | |
577 | There can also be \LaTeX\ maths in here, in ~%$~...\relax ~$%~. | |
578 | ||
579 | Files end, as a result of long tradition, with a comment | |
580 | ||
581 | : /*----- That's all, folks -------------------------------------------------*/ | |
582 | ||
583 | The closing ~#endif~ of a header file comes after this final comment. | |
584 | ||
585 | ||
1528431b MW |
586 | * COMMENT Emacs cruft |
587 | ||
588 | #+LATEX_CLASS: strayman | |
589 | ||
590 | ## LocalWords: CLOS ish destructure destructured accessor specializers | |
82892195 MW |
591 | ## LocalWords: accessors DSLs gensym gensyms bletcherous Stroustrup |
592 | ## LocalWords: Stroustrup's signedness | |
1528431b MW |
593 | |
594 | ## Local variables: | |
595 | ## mode: org | |
596 | ## End: |