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----------------------------------------------------------------------------------
66Edited version of the Linux Kernel Style Guide:
67----------------------------------------------------------------------------------
68
69                Chapter 1: Indentation
70
71Respect the indentation of the author of the original function.
72If the indentation is not consistent, don't change it.  If
73you are so anal-retentive about these things and you can't
74bare to even look at code with poor indentation, change it to 4.
75
76
77                Chapter 2: Placing Braces
78
79The other issue that always comes up in C styling is the placement of
80braces.  Unlike the indent size, there are few technical reasons to
81choose one placement strategy over the other, but the preferred way, as
82shown to us by the prophets Kernighan and Ritchie, is to put the opening
83brace last on the line, and put the closing brace first, thusly:
84
85        if (x is true) {
86                we do y
87        }
88
89However, there is one special case, namely functions: they have the
90opening brace at the beginning of the next line, thus:
91
92        int function(int x)
93        {
94                body of function
95        }
96
97Heretic people all over the world have claimed that this inconsistency
98is ...  well ...  inconsistent, but all right-thinking people know that
99(a) K&R are _right_ and (b) K&R are right.  Besides, functions are
100special anyway (you can't nest them in C). 
101
102Note that the closing brace is empty on a line of its own, _except_ in
103the cases where it is followed by a continuation of the same statement,
104ie a "while" in a do-statement or an "else" in an if-statement, like
105this:
106
107        do {
108                body of do-loop
109        } while (condition);
110
111and
112
113        if (x == y) {
114                ..
115        } else if (x > y) {
116                ...
117        } else {
118                ....
119        }
120                        
121Rationale: K&R. 
122
123Also, note that this brace-placement also minimizes the number of empty
124(or almost empty) lines, without any loss of readability.  Thus, as the
125supply of new-lines on your screen is not a renewable resource (think
12625-line terminal screens here), you have more empty lines to put
127comments on. 
128
129
130                Chapter 3: Naming
131
132C is a Spartan language, and so should your naming be.  Unlike Modula-2
133and Pascal programmers, C programmers do not use cute names like
134ThisVariableIsATemporaryCounter.  A C programmer would call that
135variable "tmp", which is much easier to write, and not the least more
136difficult to understand. 
137
138HOWEVER, while mixed-case names are frowned upon, descriptive names for
139global variables are a must.  To call a global function "foo" is a
140shooting offense. 
141
142GLOBAL variables (to be used only if you _really_ need them) need to
143have descriptive names, as do global functions.  If you have a function
144that counts the number of active users, you should call that
145"count_active_users()" or similar, you should _not_ call it "cntusr()". 
146
147Encoding the type of a function into the name (so-called Hungarian
148notation) is brain damaged - the compiler knows the types anyway and can
149check those, and it only confuses the programmer.  No wonder MicroSoft
150makes buggy programs. 
151
152LOCAL variable names should be short, and to the point.  If you have
153some random integer loop counter, it should probably be called "i". 
154Calling it "loop_counter" is non-productive, if there is no chance of it
155being mis-understood.  Similarly, "tmp" can be just about any type of
156variable that is used to hold a temporary value. 
157
158
159                
160                Chapter 4: Functions
161
162Document functions.  
163
164Keep functions as modular as possible.  But don't adhere to artificial
165line number limitations.  For example, lame_encode_frame() encodes a
166single MP3 frame and is a long sequence of function calls.  It makes
167no sense to break this into two or more routines.
168
169
170
171                Chapter 5: Commenting
172
173Comments are good, but there is also a danger of over-commenting.  NEVER
174try to explain HOW your code works in a comment: it's much better to
175write the code so that the _working_ is obvious, and it's a waste of
176time to explain badly written code. 
177
178Generally, you want your comments to tell WHAT your code does, not HOW. 
179Also, try to avoid putting comments inside a function body: if the
180function is so complex that you need to separately comment parts of it,
181you should probably go back to chapter 4 for a while.  You can make
182small comments to note or warn about something particularly clever (or
183ugly), but try to avoid excess.  Instead, put the comments at the head
184of the function, telling people what it does, and possibly WHY it does
185it. 
186
187
188