[ViewVC] Contents of: svn/trunk/xvidcore/CodingStyle

----------------------------------------------------------------------
                        XviD Core coding style

              Inspired by the Linux Kernel Coding Style

----------------------------------------------------------------------
$Id: CodingStyle,v 1.2 2002-06-12 21:23:49 edgomez Exp $


This is a short document describing the preferred coding style for the
XviD  core library.   Coding  style  is very  personal,  and we  won't
_force_  our   views  on  anybody.   But  if   everybody  who  submits
patches/codes to the  CVS respect this coding style,  the whole source
would be easier to read/understand for all the others developers.


                        Chapter 1: Indentation

Tabs are  4 characters, and  thus indentations are also  4 characters.
We use  tabs as indentation chars,  try not using spaces  as they make
the source code bigger.

In short,  8-char indents would have  made things easier  to read, and
would have the  added benefit of warning you  when you're nesting your
functions too deep. But because of  some parts of the XviD code source
has to use  lot of if/else/for statements together,  we have chosen to
set the standard tab length to 4 characters.

Setting  the tab  length to  4 doesn't  allow you  to write  deep code
paths. Try to  keep your code path as simple as  possible. More than 3
levels is  surely a piece of code  which needs to be  written again if
possible.


                      Chapter 2: Placing Braces

The other issue that always comes  up in C styling is the placement of
braces.  Unlike  the indent size,  there are few technical  reasons to
choose one placement  strategy over the other, but  the preferred way,
is to place the braces just a the end of the line : 

        if (x is true) {
            we do y
        } else {
            we do z
        }

This way we waste no lines with a single brace in it, and can add more
useful comments to the code.

Function and struct braces do not obey this rule, the braces are added
in the next line :

        int function(int x)
        {
            body of function
        }

        struct foo_t
        {
            body of the strcuture
        }
               
Note that the closing brace is empty on a line of its own, _except_ in
the cases where it is followed by a continuation of the same statement,
ie a "while" in a do-statement or an "else" in an if-statement, like
this:

        do {
            body of do-loop
        } while (condition);

and

        if (x == y) {
            ..
        } else if (x > y) {
            ...
        }
        else {
            ....
        }


                          Chapter 3: Naming

C  is  a Spartan  language,  and so  should  your  naming be.   Unlike
Modula-2 and Pascal  programmers, C programmers do not  use cute names
like ThisVariableIsATemporaryCounter.  A  C programmer would call that
variable "tmp", which is much easier  to write, and not the least more
difficult to understand.

HOWEVER, while  mixed-case names  are frowned upon,  descriptive names
for global variables are a must.  To call a global function "foo" is a
shooting offense.

GLOBAL variables (to  be used only if you _really_  need them) need to
have  descriptive  names, as  do  global  functions.   If you  have  a
function that counts the number  of active users, you should call that
"count_active_users()"   or  similar,   you  should   _not_   call  it
"cntusr()". Try not  to use global variables as  they break reentrancy
and XviD aims to be (in a long term) a threadable library.


Encoding the  type of  a function into  the name  (so-called Hungarian
notation) is brain  damaged - the compiler knows  the types anyway and
can  check those,  and it  only  confuses the  programmer.  No  wonder
MicroSoft makes buggy programs.

LOCAL variable names  should be short, and to the  point.  If you have
some random  integer loop counter,  it should probably be  called "i".
Calling it "loop_counter" is non-productive,  if there is no chance of
it being mis-understood.  Similarly, "tmp"  can be just about any type
of variable that is used to hold a temporary value.

If  you are  afraid to  mix  up your  local variable  names, you  have
another problem, which is called the function-growth-hormone-imbalance
syndrome.  See next chapter.

                
                         Chapter 4: Functions

Functions  should be short  and sweet,  and do  just one  thing.  They
should fit on one or two  screenfuls of text (the ISO/ANSI screen size
is 80x24,  as we all know),  and do one  thing and do that  well.

The  maximum length  of a  function is  inversely proportional  to the
complexity and indentation level of  that function.  So, if you have a
conceptually  simple  function that  is  just  one  long (but  simple)
case-statement, where you have to do lots of small things for a lot of
different cases, it's OK to have a longer function.

However,  if you  have  a complex  function,  and you  suspect that  a
less-than-gifted  first-year   high-school  student  might   not  even
understand what  the function is all  about, you should  adhere to the
maximum  limits  all the  more  closely.   Use  helper functions  with
descriptive names  (you can  ask the compiler  to in-line them  if you
think it's performance-critical, and it  will probably do a better job
of it that you would have done).

Another  measure of  the function  is the  number of  local variables.
They shouldn't exceed 5-10, or you're doing something wrong.  Re-think
the function,  and split  it into smaller  pieces.  A human  brain can
generally easily keep track of about 7 different things, anything more
and it gets confused.  You know you're brilliant, but maybe you'd like
to understand what you did 2 weeks from now.

NB :  This chapter does  not apply very  well to some XviD  parts, but
keep this "philosphy" in mind anyway.


                        Chapter 5: Commenting

Comments  are good,  but there  is also  a danger  of over-commenting.
NEVER  try to  explain HOW  your code  works in  a comment:  it's much
better to write the code so  that the _working_ is obvious, and it's a
waste of time to explain badly written code.

Generally, you  want your  comments to tell  WHAT your code  does, not
HOW.  Also, try  to avoid putting comments inside  a function body: if
the function is  so complex that you need  to separately comment parts
of it, you should probably go back  to chapter 4 for a while.  You can
make  small comments  to  note or  warn  about something  particularly
clever (or ugly), but try  to avoid excess.  Instead, put the comments
at the head of the function, telling people what it does, and possibly
WHY it does it.


                      Chapter 6: Emacs settings

That's OK,  we all  do.  You've probably  been told by  your long-time
Unix user helper that "GNU  emacs" automatically formats the C sources
for  you, and  you've  noticed that  yes,  it does  do  that, but  the
defaults it uses are less than desirable (in fact, they are worse than
random typing  - a  infinite number of  monkeys typing into  GNU emacs
would never make a good program).

So, you  can either get rid  of GNU emacs,  or change it to  use saner
values.  To do the latter, you  can stick the following in your .emacs
file:

(defun xvid-c-mode ()
  "C mode with adjusted defaults for use with the XviD Sources."
  (interactive)
  (c-mode)
  (message "Loading xvid-c-mode")
  (c-set-style "K&R")
  (setq c-basic-offset 4)
  (setq indent-tabs-mode t tab-width 4)
  (turn-on-follow-mode)
  (toggle-truncate-lines)
  (setq make-backup-files nil)
  (setq column-number-mode t)
)

This  will define  the "M-x  xvid-c-mode command".   When  hacking the
library, if you  put the string -*- xvid-c -*-  somewhere on the first
two lines, this mode will be automatically invoked. Also, you may want
to add

(setq auto-mode-alist (cons '("/.*/xvidcore.*/.*\\.[ch]$" . xvid-c-mode)
                            auto-mode-alist))

to  your .emacs  file if  you want  to have  xvid-c-mode  switched on
automagically when you edit source files under */xvidcore/.


                          Chapter 7: indent

But even  if you fail in getting  emacs to do sane  formatting, or you
are using  another kind of editors  (vim?, vc++??, notepad  ??? <- you
crazy :-) everything is lost: use "indent". 

Now, again, GNU indent has the same brain dead settings that GNU emacs
has, which  is why  you need to  give it  a few command  line options.
However, that's  not too  bad, because even  the makers of  GNU indent
recognize the authority  of K&R (the GNU people  aren't evil, they are
just severely misguided  in this matter), so you  just give indent the
options : 

-bad -bap -nbbo -nbc -br -c33 -cd33 -ncdb -ce -ci4 -cli0 -cp33 -cs -d0
-di1 -nfc1 -nfca -nhnl -i4 -ip0 -l79 -lp -npcs -nprs -psl -saf -sai
-saw -nsc -nsob -nss -ut -ts4 -bfda

Look at the  man pages for more details  about each option. Basically,
our style is very close to the K&R one.

"indent" has a lot of options, and especially when it comes to comment
re-formatting you  may want to  take a look  at the manual  page.  But
remember: "indent" is not a fix for bad programming.


                        Chapter 8: Reentrance

Well, at  the moment, XviD is  not a reentrant  library because during
its development, some mistakes have  been comited. But reentrance is a
long term aim  for this project so you should not  write code which is
not reentrant.

To ensure you're writting reentrant code, check that :

  - you're not using global variables (except constants because
    they're used in read only access). 
  - you're not using static variables (except constants because
    they're used in read only access).
  - functions use only local variables.
  - functions do not return data locally allocated on the stack.


                           Chapter 9: Types

A while  ago, almost  all variables got  an extra type,  like int32_t,
uint8_t  etc...  to make  them  of  identical  size on  all  platforms
(defined in compiler specific  headers or in src/portab.h). You should
use  those  types  only  when  really needed.  When  defining  a  loop
variable, you must  use platform natural types defined  as 'int'. This
makes the code  faster because the compiler transforms  the int in the
natural size  of the CPU :  32 bit on  32 bit CPUs (x86,  powerpc) and
64bit on 64 bit CPUs (ultra sparc, AMD hammer, Intel Itanium, Motorola
powerpc64)

But  don't forget  that  the  minimum platform  targeted  by the  XviD
library is a  32bit cpu. So a  'int' should (never say 'is'  in such a
case) always be 32bit long (or bigger)


                       Chapter 10: Portability

The  code  _must_ be  portable.  Don't  use  specific functions  to  a
compiler/OS/libC.  Don't  use  specific  compiler pragmas,  or  syntax
extensions. 

Btw, if you  have to use those deprecated/not  portable features, then
use the src/portab.h to write a wrapper for each targeted system. 

For the moment, the supported platforms are :
  - Win32 family (x86) with VC++
  - Cygwin env (bypassing the cygwin.dll with -mno-cygwin flag)
  - Mingw ???
  - GNU/Linux (x86 and  ppc for optimized code, or  any other arch for
    the pure C version of the library)
  - *BSD (same archs as GNU/Linux)
Revision:	197
Committed:	Wed Jun 12 21:23:49 2002 UTC (22 years, 4 months ago) by edgomez
File size:	11068 byte(s)
Error occurred while calculating annotation data.
Log Message:	Added the $Id$ RCS keyword
#	Content
1	----------------------------------------------------------------------
2	XviD Core coding style
3
4	Inspired by the Linux Kernel Coding Style
5
6	----------------------------------------------------------------------
7	$Id: CodingStyle,v 1.2 2002-06-12 21:23:49 edgomez Exp $
8
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)