Parent Directory
|
Revision Log
Revision 197 - (view) (download)
1 : | edgomez | 196 | ---------------------------------------------------------------------- |
2 : | XviD Core coding style | ||
3 : | |||
4 : | Inspired by the Linux Kernel Coding Style | ||
5 : | |||
6 : | ---------------------------------------------------------------------- | ||
7 : | edgomez | 197 | $Id: CodingStyle,v 1.2 2002-06-12 21:23:49 edgomez Exp $ |
8 : | edgomez | 196 | |
9 : | |||
10 : | This is a short document describing the preferred coding style for the | ||
11 : | XviD core library. Coding style is very personal, and we won't | ||
12 : | _force_ our views on anybody. But if everybody who submits | ||
13 : | patches/codes to the CVS respect this coding style, the whole source | ||
14 : | would be easier to read/understand for all the others developers. | ||
15 : | |||
16 : | |||
17 : | |||
18 : | Chapter 1: Indentation | ||
19 : | |||
20 : | Tabs are 4 characters, and thus indentations are also 4 characters. | ||
21 : | We use tabs as indentation chars, try not using spaces as they make | ||
22 : | the source code bigger. | ||
23 : | |||
24 : | In short, 8-char indents would have made things easier to read, and | ||
25 : | would have the added benefit of warning you when you're nesting your | ||
26 : | functions too deep. But because of some parts of the XviD code source | ||
27 : | has to use lot of if/else/for statements together, we have chosen to | ||
28 : | set the standard tab length to 4 characters. | ||
29 : | |||
30 : | Setting the tab length to 4 doesn't allow you to write deep code | ||
31 : | paths. Try to keep your code path as simple as possible. More than 3 | ||
32 : | levels is surely a piece of code which needs to be written again if | ||
33 : | possible. | ||
34 : | |||
35 : | |||
36 : | Chapter 2: Placing Braces | ||
37 : | |||
38 : | The other issue that always comes up in C styling is the placement of | ||
39 : | braces. Unlike the indent size, there are few technical reasons to | ||
40 : | choose one placement strategy over the other, but the preferred way, | ||
41 : | is to place the braces just a the end of the line : | ||
42 : | |||
43 : | if (x is true) { | ||
44 : | we do y | ||
45 : | } else { | ||
46 : | we do z | ||
47 : | } | ||
48 : | |||
49 : | This way we waste no lines with a single brace in it, and can add more | ||
50 : | useful comments to the code. | ||
51 : | |||
52 : | Function and struct braces do not obey this rule, the braces are added | ||
53 : | in the next line : | ||
54 : | |||
55 : | int function(int x) | ||
56 : | { | ||
57 : | body of function | ||
58 : | } | ||
59 : | |||
60 : | struct foo_t | ||
61 : | { | ||
62 : | body of the strcuture | ||
63 : | } | ||
64 : | |||
65 : | Note that the closing brace is empty on a line of its own, _except_ in | ||
66 : | the cases where it is followed by a continuation of the same statement, | ||
67 : | ie a "while" in a do-statement or an "else" in an if-statement, like | ||
68 : | this: | ||
69 : | |||
70 : | do { | ||
71 : | body of do-loop | ||
72 : | } while (condition); | ||
73 : | |||
74 : | and | ||
75 : | |||
76 : | if (x == y) { | ||
77 : | .. | ||
78 : | } else if (x > y) { | ||
79 : | ... | ||
80 : | } | ||
81 : | else { | ||
82 : | .... | ||
83 : | } | ||
84 : | |||
85 : | |||
86 : | Chapter 3: Naming | ||
87 : | |||
88 : | C is a Spartan language, and so should your naming be. Unlike | ||
89 : | Modula-2 and Pascal programmers, C programmers do not use cute names | ||
90 : | like ThisVariableIsATemporaryCounter. A C programmer would call that | ||
91 : | variable "tmp", which is much easier to write, and not the least more | ||
92 : | difficult to understand. | ||
93 : | |||
94 : | HOWEVER, while mixed-case names are frowned upon, descriptive names | ||
95 : | for global variables are a must. To call a global function "foo" is a | ||
96 : | shooting offense. | ||
97 : | |||
98 : | GLOBAL variables (to be used only if you _really_ need them) need to | ||
99 : | have descriptive names, as do global functions. If you have a | ||
100 : | function that counts the number of active users, you should call that | ||
101 : | "count_active_users()" or similar, you should _not_ call it | ||
102 : | "cntusr()". Try not to use global variables as they break reentrancy | ||
103 : | and XviD aims to be (in a long term) a threadable library. | ||
104 : | |||
105 : | |||
106 : | Encoding the type of a function into the name (so-called Hungarian | ||
107 : | notation) is brain damaged - the compiler knows the types anyway and | ||
108 : | can check those, and it only confuses the programmer. No wonder | ||
109 : | MicroSoft makes buggy programs. | ||
110 : | |||
111 : | LOCAL variable names should be short, and to the point. If you have | ||
112 : | some random integer loop counter, it should probably be called "i". | ||
113 : | Calling it "loop_counter" is non-productive, if there is no chance of | ||
114 : | it being mis-understood. Similarly, "tmp" can be just about any type | ||
115 : | of variable that is used to hold a temporary value. | ||
116 : | |||
117 : | If you are afraid to mix up your local variable names, you have | ||
118 : | another problem, which is called the function-growth-hormone-imbalance | ||
119 : | syndrome. See next chapter. | ||
120 : | |||
121 : | |||
122 : | Chapter 4: Functions | ||
123 : | |||
124 : | Functions should be short and sweet, and do just one thing. They | ||
125 : | should fit on one or two screenfuls of text (the ISO/ANSI screen size | ||
126 : | is 80x24, as we all know), and do one thing and do that well. | ||
127 : | |||
128 : | The maximum length of a function is inversely proportional to the | ||
129 : | complexity and indentation level of that function. So, if you have a | ||
130 : | conceptually simple function that is just one long (but simple) | ||
131 : | case-statement, where you have to do lots of small things for a lot of | ||
132 : | different cases, it's OK to have a longer function. | ||
133 : | |||
134 : | However, if you have a complex function, and you suspect that a | ||
135 : | less-than-gifted first-year high-school student might not even | ||
136 : | understand what the function is all about, you should adhere to the | ||
137 : | maximum limits all the more closely. Use helper functions with | ||
138 : | descriptive names (you can ask the compiler to in-line them if you | ||
139 : | think it's performance-critical, and it will probably do a better job | ||
140 : | of it that you would have done). | ||
141 : | |||
142 : | Another measure of the function is the number of local variables. | ||
143 : | They shouldn't exceed 5-10, or you're doing something wrong. Re-think | ||
144 : | the function, and split it into smaller pieces. A human brain can | ||
145 : | generally easily keep track of about 7 different things, anything more | ||
146 : | and it gets confused. You know you're brilliant, but maybe you'd like | ||
147 : | to understand what you did 2 weeks from now. | ||
148 : | |||
149 : | NB : This chapter does not apply very well to some XviD parts, but | ||
150 : | keep this "philosphy" in mind anyway. | ||
151 : | |||
152 : | |||
153 : | Chapter 5: Commenting | ||
154 : | |||
155 : | Comments are good, but there is also a danger of over-commenting. | ||
156 : | NEVER try to explain HOW your code works in a comment: it's much | ||
157 : | better to write the code so that the _working_ is obvious, and it's a | ||
158 : | waste of time to explain badly written code. | ||
159 : | |||
160 : | Generally, you want your comments to tell WHAT your code does, not | ||
161 : | HOW. Also, try to avoid putting comments inside a function body: if | ||
162 : | the function is so complex that you need to separately comment parts | ||
163 : | of it, you should probably go back to chapter 4 for a while. You can | ||
164 : | make small comments to note or warn about something particularly | ||
165 : | clever (or ugly), but try to avoid excess. Instead, put the comments | ||
166 : | at the head of the function, telling people what it does, and possibly | ||
167 : | WHY it does it. | ||
168 : | |||
169 : | |||
170 : | Chapter 6: Emacs settings | ||
171 : | |||
172 : | That's OK, we all do. You've probably been told by your long-time | ||
173 : | Unix user helper that "GNU emacs" automatically formats the C sources | ||
174 : | for you, and you've noticed that yes, it does do that, but the | ||
175 : | defaults it uses are less than desirable (in fact, they are worse than | ||
176 : | random typing - a infinite number of monkeys typing into GNU emacs | ||
177 : | would never make a good program). | ||
178 : | |||
179 : | So, you can either get rid of GNU emacs, or change it to use saner | ||
180 : | values. To do the latter, you can stick the following in your .emacs | ||
181 : | file: | ||
182 : | |||
183 : | (defun xvid-c-mode () | ||
184 : | "C mode with adjusted defaults for use with the XviD Sources." | ||
185 : | (interactive) | ||
186 : | (c-mode) | ||
187 : | (message "Loading xvid-c-mode") | ||
188 : | (c-set-style "K&R") | ||
189 : | (setq c-basic-offset 4) | ||
190 : | (setq indent-tabs-mode t tab-width 4) | ||
191 : | (turn-on-follow-mode) | ||
192 : | (toggle-truncate-lines) | ||
193 : | (setq make-backup-files nil) | ||
194 : | (setq column-number-mode t) | ||
195 : | ) | ||
196 : | |||
197 : | This will define the "M-x xvid-c-mode command". When hacking the | ||
198 : | library, if you put the string -*- xvid-c -*- somewhere on the first | ||
199 : | two lines, this mode will be automatically invoked. Also, you may want | ||
200 : | to add | ||
201 : | |||
202 : | (setq auto-mode-alist (cons '("/.*/xvidcore.*/.*\\.[ch]$" . xvid-c-mode) | ||
203 : | auto-mode-alist)) | ||
204 : | |||
205 : | to your .emacs file if you want to have xvid-c-mode switched on | ||
206 : | automagically when you edit source files under */xvidcore/. | ||
207 : | |||
208 : | |||
209 : | Chapter 7: indent | ||
210 : | |||
211 : | But even if you fail in getting emacs to do sane formatting, or you | ||
212 : | are using another kind of editors (vim?, vc++??, notepad ??? <- you | ||
213 : | crazy :-) everything is lost: use "indent". | ||
214 : | |||
215 : | Now, again, GNU indent has the same brain dead settings that GNU emacs | ||
216 : | has, which is why you need to give it a few command line options. | ||
217 : | However, that's not too bad, because even the makers of GNU indent | ||
218 : | recognize the authority of K&R (the GNU people aren't evil, they are | ||
219 : | just severely misguided in this matter), so you just give indent the | ||
220 : | options : | ||
221 : | |||
222 : | -bad -bap -nbbo -nbc -br -c33 -cd33 -ncdb -ce -ci4 -cli0 -cp33 -cs -d0 | ||
223 : | -di1 -nfc1 -nfca -nhnl -i4 -ip0 -l79 -lp -npcs -nprs -psl -saf -sai | ||
224 : | -saw -nsc -nsob -nss -ut -ts4 -bfda | ||
225 : | |||
226 : | Look at the man pages for more details about each option. Basically, | ||
227 : | our style is very close to the K&R one. | ||
228 : | |||
229 : | "indent" has a lot of options, and especially when it comes to comment | ||
230 : | re-formatting you may want to take a look at the manual page. But | ||
231 : | remember: "indent" is not a fix for bad programming. | ||
232 : | |||
233 : | |||
234 : | Chapter 8: Reentrance | ||
235 : | |||
236 : | Well, at the moment, XviD is not a reentrant library because during | ||
237 : | its development, some mistakes have been comited. But reentrance is a | ||
238 : | long term aim for this project so you should not write code which is | ||
239 : | not reentrant. | ||
240 : | |||
241 : | To ensure you're writting reentrant code, check that : | ||
242 : | |||
243 : | - you're not using global variables (except constants because | ||
244 : | they're used in read only access). | ||
245 : | - you're not using static variables (except constants because | ||
246 : | they're used in read only access). | ||
247 : | - functions use only local variables. | ||
248 : | - functions do not return data locally allocated on the stack. | ||
249 : | |||
250 : | |||
251 : | Chapter 9: Types | ||
252 : | |||
253 : | A while ago, almost all variables got an extra type, like int32_t, | ||
254 : | uint8_t etc... to make them of identical size on all platforms | ||
255 : | (defined in compiler specific headers or in src/portab.h). You should | ||
256 : | use those types only when really needed. When defining a loop | ||
257 : | variable, you must use platform natural types defined as 'int'. This | ||
258 : | makes the code faster because the compiler transforms the int in the | ||
259 : | natural size of the CPU : 32 bit on 32 bit CPUs (x86, powerpc) and | ||
260 : | 64bit on 64 bit CPUs (ultra sparc, AMD hammer, Intel Itanium, Motorola | ||
261 : | powerpc64) | ||
262 : | |||
263 : | But don't forget that the minimum platform targeted by the XviD | ||
264 : | library is a 32bit cpu. So a 'int' should (never say 'is' in such a | ||
265 : | case) always be 32bit long (or bigger) | ||
266 : | |||
267 : | |||
268 : | Chapter 10: Portability | ||
269 : | |||
270 : | The code _must_ be portable. Don't use specific functions to a | ||
271 : | compiler/OS/libC. Don't use specific compiler pragmas, or syntax | ||
272 : | extensions. | ||
273 : | |||
274 : | Btw, if you have to use those deprecated/not portable features, then | ||
275 : | use the src/portab.h to write a wrapper for each targeted system. | ||
276 : | |||
277 : | For the moment, the supported platforms are : | ||
278 : | - Win32 family (x86) with VC++ | ||
279 : | - Cygwin env (bypassing the cygwin.dll with -mno-cygwin flag) | ||
280 : | - Mingw ??? | ||
281 : | - GNU/Linux (x86 and ppc for optimized code, or any other arch for | ||
282 : | the pure C version of the library) | ||
283 : | - *BSD (same archs as GNU/Linux) |
No admin address has been configured | ViewVC Help |
Powered by ViewVC 1.0.4 |