[svn] / trunk / xvidcore / CodingStyle Repository:
ViewVC logotype

View of /trunk/xvidcore/CodingStyle

Parent Directory Parent Directory | Revision Log Revision Log

Revision 197 - (download) (annotate)
Wed Jun 12 21:23:49 2002 UTC (17 years, 1 month ago) by edgomez
File size: 11068 byte(s)
Added the $Id$ RCS keyword
			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

		      Chapter 2: Placing Braces

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

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


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

			  Chapter 3: Naming

like ThisVariableIsATemporaryCounter.  A  C programmer would call that
difficult to understand.

shooting offense.

"cntusr()". Try not  to use global variables as  they break reentrancy
and XviD aims to be (in a long term) a threadable library.

MicroSoft makes buggy programs.

of variable that is used to hold a temporary value.

syndrome.  See next chapter.

			 Chapter 4: Functions


The  maximum length  of a  function is  inversely proportional  to the
conceptually  simple  function that  is  just  one  long (but  simple)
different cases, it's OK to have a longer function.

maximum  limits  all the  more  closely.   Use  helper functions  with
of it that you would have done).

Another  measure of  the function  is the  number of  local variables.
generally easily keep track of about 7 different things, anything more
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

waste of time to explain badly written code.

the function is  so complex that you need  to separately comment parts
make  small comments  to  note or  warn  about something  particularly
WHY it does it.

		      Chapter 6: Emacs settings

random typing  - a  infinite number of  monkeys typing into  GNU emacs
would never make a good program).


(defun xvid-c-mode ()
  "C mode with adjusted defaults for use with the XviD Sources."
  (message "Loading xvid-c-mode")
  (c-set-style "K&R")
  (setq c-basic-offset 4)
  (setq indent-tabs-mode t tab-width 4)
  (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
to add

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

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". 

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.


			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

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

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)

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