4. The Source Code

These are some rough guidelines with regard the source code organization and style.

4.1. Coding Style Guidelines

Due to the fact that several different programming languages are being used throughout the Arabeyes project it is impossible to set a unifying coding guideline. A good source of information is the GNU Coding Standards.

The most important rule here is consistency. You must be consistent throughout your entire source tree in every convention you do. The way variables, constants, etc. are named must be consistent throughout your entire source tree. The way you indent must be consistent as well (space, tabs, etc.).

4.2. File Naming Conventions

All source code files should be in lower-case. This also goes for directory names. In fact, generally all files should be in lower-case. There is one exception to this, which are the files mentioned here.

It is worth noting that there may be some exceptions. For example, Java dictates that you name your files as you have named your classes. It is common programming practice with Java to capitalize your class names. For this reason, it makes sense to capitalize your filenames as well.

4.3. The Use of Autotools

It is strongly recommended that you use autotools when putting together your project. The use of autotools could require a considerable learning curve. Thankfully there are programs that help with this (autoproject being one of them). The Autobook may also prove to be a valuable resource.

Autotools generate quite a few files in the process. As you probably know by now, files that are generated by other files on CVS are not permitted on CVS. That is, if you have runme.sh which creates x.txt then you should not have x.txt on CVS. It is also not permitted to have files that are generated by standard tools (e.g. autoconf) to be present in CVS. For this reason you will need to bootstrap your project. The Bootstrapping chapter of the Autotools book explains this issue well.

It is recommended that you bootstrap your project depending on the tools used. For instance, if it is a GNOME-based project, it is recommended you use the autogen.sh to boostrap. If it is a KDE-based project then it is recommended to use the Makefile.cvs to boostrap. However, if your project does not belong to a specific group of toolkits, you should default to the bootstrap file as outlined in the Autotools book.

Example 1. bootstrap file

#!/bin/sh
#--
# Bootstrap for BiCon
# $Id: developer-guide.en.xml,v 1.7 2004/11/06 00:15:09 elzubeir Exp $
#--

# Run this file to produce a configure script.

DEFAULTARGS="--force --install --autoreconf=auto"

for arg in $DEFAULTARGS $*
do
	case $arg in
		-h | --help)
			HELP=--help ;;
		-V | --version)
			VERSION=--version ;;
		-v | --verbose)
			VERBOSE=--verbose ;;
		-d | --debug)
			DEBUG=--debug ;;
		-W | --warning | --warnings=yes)
			WARNINGS=--warnings=all ;;
		--no-warning | --warnings=no)
			WARNINGS= ;;
		--warning=*)
			WARNINGS=$arg ;;
		-f | --force | --force=yes | --force-missing)
			FORCE=--force ;;
		--no-force | --force=no)
			FORCE=--no-force ;;
		-i | --install | --install=yes | -a | --add-missing)
			INSTALL=--install ;;
		--no-install | --install=no)
			INSTALL= ;;
		-s | --symlink | --symlink=yes | --no-copy | --copy=no)
			SYMLINK=--symlink ;;
		--no-symlink | --symlink=no | --copy | --copy=yes)
			SYMLINK= ;;
		-m | --make | --make=yes)
			MAKE=--make ;;
		--no-make | --make=no)
			MAKE= ;;
		-n | --dry-run)
			DRYRUN=echo ;;
		--autoreconf=auto)
			AUTORECONF=auto ;;
		--autoreconf | --autoreconf=yes)
			AUTORECONF=yes ;;
		--no-autoreconf | --autoreconf=no)
			AUTORECONF= ;;
		*)
			echo Ignoring unknown parameter $arg
	esac
done

test -z "$SYMLINK" && COPY=--copy
test -n "$INSTALL" && ADDMISSING=--add-missing

# use autoreconf if possible, just check for version 2+
if test "$AUTORECONF" = auto; then
	case `autoreconf --version 2>/dev/null` in
		*"autoreconf (GNU Autoconf) 2."* )
			echo Usable autoreconf found, running
		;;
		*)
			AUTORECONF=
		;;
	esac
fi

if test -n "$AUTORECONF";  then
	$DRYRUN autoreconf $HELP $VERSION $VERBOSE $DEBUG $FORCE $INSTALL $SYMLINK $MAKE $WARNINGS
	exit $?
fi

# add files 'config.guess', 'config.sub', 'ltconfig', 'ltmain.sh'
$DRYRUN libtoolize $HELP $VERSION --automake $COPY $DEBUG $FORCE || exit 1

# generate 'aclocal.m4'
if test -f configure.ac -o configure.in; then
	$DRYRUN aclocal $HELP $VERSION $VERBOSE $FORCE || exit 1
fi

# generate 'config.h.in'
if test -f configure.ac -o configure.in; then
	$DRYRUN autoheader $HELP $VERSION $VERBOSE $DEBUG $FORCE $WARNINGS || exit 1
fi

#  generate Makefile.in's from Makefile.am's
if test -f Makefile.am; then
	$DRYRUN automake $HELP $VERSION $VERBOSE $ADDMISSING $COPY $FORCE $WARNINGS || exit 1
fi

# generate configure from configure.ac
if test -f configure.ac -o -f configure.in; then
	$DRYRUN autoconf $HELP $VERSION $VERBOSE $DEBUG $FORCE $WARNINGS || exit 1
fi

if test -n "$MAKE"; then
	if test -f ./configure; then
		$DRYRUN ./configure $HELP $VERSION || exit 1
	fi
	if test -f Makefile; then
		$DRYRUN make || exit 1
	fi
fi
        

Feel free to use the above in your program, with whatever modifications you may need to make. Different people have different tastes in how they want to boostrap their project. As long as you do have a sensible mechanism to boostrap, you are good to go, but whatever you do, you cannot leave auto-generated files from autotools in CVS.