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