| 1 |
* The LAME API is frozen. Poorly designed as it is, don't change it, |
| 2 |
and add to it sparingly. |
| 3 |
|
| 4 |
* Don't take it upon yourself to go through LAME with the sole purpose |
| 5 |
of updating everything to match this guide. Especially important: |
| 6 |
don't change the spacing, indentation, curly braces, etc, |
| 7 |
in routines you did not write. |
| 8 |
|
| 9 |
* If you want to make a change which effects many many functions, |
| 10 |
please check with the maintainer first. |
| 11 |
|
| 12 |
* Respect the indentation of the author of the original function. |
| 13 |
If the indentation is not consistent, use 4. |
| 14 |
|
| 15 |
* Don't use tabulators (the character with the value '\t') in source code, |
| 16 |
especially these with a width of unequal 8. Lame sources are using |
| 17 |
different sizes for tabulators. |
| 18 |
|
| 19 |
* Don't set the macro NDEBUG in alpha versons. |
| 20 |
NDEBUG should be set for beta versions. |
| 21 |
|
| 22 |
* check important assumptions with an assert() |
| 23 |
|
| 24 |
* use int for all integer quantities. |
| 25 |
LAME requires 32 bit ints, so you can assume int is at least 32 bits. |
| 26 |
Don't use 'long'. Don't use 'unsigned' unless ABSOLUTELY necessary. |
| 27 |
Don't use 'char' just to save bytes. If 64 bits is required, use int64. |
| 28 |
|
| 29 |
Annnotation: |
| 30 |
ISO C calls the 64 bit int type not int64 but int64_t. |
| 31 |
|
| 32 |
* Avoid using float or double, and instead use: (defined in machine.h). |
| 33 |
|
| 34 |
FLOAT for variables which require at least 32bits |
| 35 |
FLOAT8 for variables which require at least 64bits |
| 36 |
|
| 37 |
On some machines, 64bit will be faster than 32bit. Also, some math |
| 38 |
routines require 64bit float, so setting FLOAT=float will result in a |
| 39 |
lot of conversions. |
| 40 |
|
| 41 |
Annotation (pfk): |
| 42 |
The new ISO C standard passed in autumn 1999 has defined new types for |
| 43 |
exactly this reason. There are called float_least32_t and float_least64_t |
| 44 |
and have at least the advantage that you not need to explain their |
| 45 |
meaning. |
| 46 |
|
| 47 |
Annotation (mt): |
| 48 |
we will adopt this convention in Jan 1, 2003. |
| 49 |
|
| 50 |
|
| 51 |
* The internal representation of PCM samples in type 'sample_t', |
| 52 |
currently this is a FLOAT. |
| 53 |
|
| 54 |
* Use SI base units. Lame mixes Hz, kHz, kbps, bps. This is mess. |
| 55 |
|
| 56 |
Example: |
| 57 |
float wavelength_green = 555.e-9; |
| 58 |
unsigned data_rate = 128000; |
| 59 |
float lowpass_freq = 12500.; |
| 60 |
|
| 61 |
Converting between user input and internal representation should be done |
| 62 |
near the user interface, not in the most inner loop of an utility |
| 63 |
function. |
| 64 |
|
| 65 |
---------------------------------------------------------------------------------- |
| 66 |
Edited version of the Linux Kernel Style Guide: |
| 67 |
---------------------------------------------------------------------------------- |
| 68 |
|
| 69 |
Chapter 1: Indentation |
| 70 |
|
| 71 |
Respect the indentation of the author of the original function. |
| 72 |
If the indentation is not consistent, don't change it. If |
| 73 |
you are so anal-retentive about these things and you can't |
| 74 |
bare to even look at code with poor indentation, change it to 4. |
| 75 |
|
| 76 |
|
| 77 |
Chapter 2: Placing Braces |
| 78 |
|
| 79 |
The other issue that always comes up in C styling is the placement of |
| 80 |
braces. Unlike the indent size, there are few technical reasons to |
| 81 |
choose one placement strategy over the other, but the preferred way, as |
| 82 |
shown to us by the prophets Kernighan and Ritchie, is to put the opening |
| 83 |
brace last on the line, and put the closing brace first, thusly: |
| 84 |
|
| 85 |
if (x is true) { |
| 86 |
we do y |
| 87 |
} |
| 88 |
|
| 89 |
However, there is one special case, namely functions: they have the |
| 90 |
opening brace at the beginning of the next line, thus: |
| 91 |
|
| 92 |
int function(int x) |
| 93 |
{ |
| 94 |
body of function |
| 95 |
} |
| 96 |
|
| 97 |
Heretic people all over the world have claimed that this inconsistency |
| 98 |
is ... well ... inconsistent, but all right-thinking people know that |
| 99 |
(a) K&R are _right_ and (b) K&R are right. Besides, functions are |
| 100 |
special anyway (you can't nest them in C). |
| 101 |
|
| 102 |
Note that the closing brace is empty on a line of its own, _except_ in |
| 103 |
the cases where it is followed by a continuation of the same statement, |
| 104 |
ie a "while" in a do-statement or an "else" in an if-statement, like |
| 105 |
this: |
| 106 |
|
| 107 |
do { |
| 108 |
body of do-loop |
| 109 |
} while (condition); |
| 110 |
|
| 111 |
and |
| 112 |
|
| 113 |
if (x == y) { |
| 114 |
.. |
| 115 |
} else if (x > y) { |
| 116 |
... |
| 117 |
} else { |
| 118 |
.... |
| 119 |
} |
| 120 |
|
| 121 |
Rationale: K&R. |
| 122 |
|
| 123 |
Also, note that this brace-placement also minimizes the number of empty |
| 124 |
(or almost empty) lines, without any loss of readability. Thus, as the |
| 125 |
supply of new-lines on your screen is not a renewable resource (think |
| 126 |
25-line terminal screens here), you have more empty lines to put |
| 127 |
comments on. |
| 128 |
|
| 129 |
|
| 130 |
Chapter 3: Naming |
| 131 |
|
| 132 |
C is a Spartan language, and so should your naming be. Unlike Modula-2 |
| 133 |
and Pascal programmers, C programmers do not use cute names like |
| 134 |
ThisVariableIsATemporaryCounter. A C programmer would call that |
| 135 |
variable "tmp", which is much easier to write, and not the least more |
| 136 |
difficult to understand. |
| 137 |
|
| 138 |
HOWEVER, while mixed-case names are frowned upon, descriptive names for |
| 139 |
global variables are a must. To call a global function "foo" is a |
| 140 |
shooting offense. |
| 141 |
|
| 142 |
GLOBAL variables (to be used only if you _really_ need them) need to |
| 143 |
have descriptive names, as do global functions. If you have a function |
| 144 |
that counts the number of active users, you should call that |
| 145 |
"count_active_users()" or similar, you should _not_ call it "cntusr()". |
| 146 |
|
| 147 |
Encoding the type of a function into the name (so-called Hungarian |
| 148 |
notation) is brain damaged - the compiler knows the types anyway and can |
| 149 |
check those, and it only confuses the programmer. No wonder MicroSoft |
| 150 |
makes buggy programs. |
| 151 |
|
| 152 |
LOCAL variable names should be short, and to the point. If you have |
| 153 |
some random integer loop counter, it should probably be called "i". |
| 154 |
Calling it "loop_counter" is non-productive, if there is no chance of it |
| 155 |
being mis-understood. Similarly, "tmp" can be just about any type of |
| 156 |
variable that is used to hold a temporary value. |
| 157 |
|
| 158 |
|
| 159 |
|
| 160 |
Chapter 4: Functions |
| 161 |
|
| 162 |
Document functions. |
| 163 |
|
| 164 |
Keep functions as modular as possible. But don't adhere to artificial |
| 165 |
line number limitations. For example, lame_encode_frame() encodes a |
| 166 |
single MP3 frame and is a long sequence of function calls. It makes |
| 167 |
no sense to break this into two or more routines. |
| 168 |
|
| 169 |
|
| 170 |
|
| 171 |
Chapter 5: Commenting |
| 172 |
|
| 173 |
Comments are good, but there is also a danger of over-commenting. NEVER |
| 174 |
try to explain HOW your code works in a comment: it's much better to |
| 175 |
write the code so that the _working_ is obvious, and it's a waste of |
| 176 |
time to explain badly written code. |
| 177 |
|
| 178 |
Generally, you want your comments to tell WHAT your code does, not HOW. |
| 179 |
Also, try to avoid putting comments inside a function body: if the |
| 180 |
function is so complex that you need to separately comment parts of it, |
| 181 |
you should probably go back to chapter 4 for a while. You can make |
| 182 |
small comments to note or warn about something particularly clever (or |
| 183 |
ugly), but try to avoid excess. Instead, put the comments at the head |
| 184 |
of the function, telling people what it does, and possibly WHY it does |
| 185 |
it. |
| 186 |
|
| 187 |
|