[svn] / trunk / xvidcore / CodingStyle Repository:
ViewVC logotype

Annotation of /trunk/xvidcore/CodingStyle

Parent Directory Parent Directory | Revision Log 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