[svn] / branches / dev-api-4 / xvidcore / CodingStyle Repository:
ViewVC logotype

Annotation of /branches/dev-api-4/xvidcore/CodingStyle

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1207 - (view) (download)

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

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