Preface
This document is part of the LiveSupport
project, Copyright © 2004 Media
Development Loan Fund, under the GNU GPL.
- Author: $Author: tomas $
- Version: $Revision: 1.3 $
- Location: $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/fileConventions.html,v $
Scope
This document describes the conventions used for files in the
LiveSupport project.
Introduction
To facilitate cooperation between multiple contributors, it is
advisable to have common file conventions, so as the result of
different peoples work have a uniform look and form. This document
lists the file conventions for the different file formats used by the
project.
Where the description of the conventions is ambiguous, the examples
given are binding, and are to be followed.
Generic conventions
In general, all documents have the following structure:
- header
- partition1
- partition2
- ...
- partitionN
header
The header of the file holds:
- a reference to the LiveSupport project itself
- copyright information
- reference to the license of the file
- the latest author of the file
- the current version of the file
- the full location of the file in the configuration management
system
Following the GNU GPL guidelines on
applying a license term to source files, the typical header for a text
file looks like the following:
Copyright (c) 2004 Media Development Loan Fund
This file is part of the LiveSupport project.
http://livesupport.campware.org/
To report bugs, send an e-mail to bugs@campware.org
LiveSupport is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
LiveSupport is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with LiveSupport; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Author : $Author: tomas $
Version : $Revision: 1.3 $
Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/fileConventions.html,v $
Note the CVS keywords (as an example) for having up-to-date information
on the author, version and location of the file.
partitions
Each file is split into separate partitions, and maintains its
structure with the fixed sequence of these partitions. File formats
differ heavily on the capabilities of defining partitions - some have
explicit support (like HTML with headers and paragraphs), while in some
the commenting feature can be used to visually split up the file (like
comments in source code).
The exact nature and sequence of the partitions is dependent on the
nature of the file itself.
Generic text-based conventions
The majority (if not) all sources files are text-based. As a general
rule, text-based files adhere to the following conventions in the
LiveSupport project:
UTF-8
Whenever possible, the text files should be saved in the UTF-8 character
encoding, to enable all characters within covered by the Unicode
character set.
80 columns
Don't exceed 80 columns for any line in the file, unless it's
absolutely necessary (like having a single expression over 80 columns
that can not be broken up by a new-line character).
no tabs - 4 spaces
Don't use the tab character in text files - use 4 spaces instead for
indentation.
Specific conventions
For specific file conventions, see the separate descriptions below.
html
convention and template.
shell scripts
convention and template.
Makefiles
convention and template.
Autoconf configure files
convention and template.
C++ files
There are specific conventions for the header files and the source
files.
C++ header files
convention and template.
C++ source files
convention and template.
PHP scripts
convention and template
(downlodable version).