[svn] / branches / release-0_9_1-fixes / xvidcore / CodingStyle Repository:
ViewVC logotype

Annotation of /branches/release-0_9_1-fixes/xvidcore/CodingStyle

Parent Directory Parent Directory | Revision Log Revision Log


Revision 196 - (view) (download)
Original Path: trunk/xvidcore/CodingStyle

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

No admin address has been configured
ViewVC Help
Powered by ViewVC 1.0.4