Preface

Author: $Author: paul $
Version: $Revision: 2373 $
Location: $URL: svn://code.campware.org/campcaster/trunk/campcaster/doc/developmentEnvironment/fileConventions.html $

Scope

This document describes the conventions used for files in the Campcaster 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 Campcaster 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 Campcaster project.
    https://www.campware.org/
    To report bugs, send an e-mail to [email protected]
 
    Campcaster 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.
 
    Campcaster 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 Campcaster; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 
 
    Author   : $Author: paul $
    Version  : $Revision: 2373 $
    Location : $URL: svn://code.campware.org/campcaster/trunk/campcaster/doc/developmentEnvironment/fileConventions.html $

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 Campcaster 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).