head	1.2;
access;
symbols;
locks; strict;
comment	@# @;


1.2
date	2004.04.27.21.22.00;	author brlcad;	state Exp;
branches;
next	1.1;

1.1
date	2004.04.13.04.05.30;	author brlcad;	state Exp;
branches;
next	;


desc
@@


1.2
log
@actual developer info..  lay down the conventions.
@
text
@BRL-CAD Website Developers
==========================

The website is mainly written in php using a template-driven design to
encourage separation of site organization and logic from the
presentation and style.  The template system is a customized caching
class that does not require any special syntax in the templates
themselves, i.e. the templates themselves are just php.  For the most
part, beyond basic site frameworking and accounting, the style and
appearance are driven by css stylesheets.

The website sourcecode lives in the following directories:

htdocs/			- the BRL-CAD web root
       images/		- images should reside in here
       include/ 	- common php classes and css
misc/			- miscellaneous scripts and datafiles


Coding Conventions
------------------

Please adhere to the following conventions when working on the BRL-CAD
website sources.  If you plan on contributing to the website, we would
like you to follow certain guidelines so that some degree of
consistency and familiarity is achieved.  Contributions that don't
conform are likely to be ridiculed and rejected until they do.

PHP files use the '.php' extension.  Files used in PHP as
include/require files should use the '.inc.php' extension.  Hypertext
files not containing logic may be named as either '.php' or '.html'.

Filenames should be lowercase for all files that will be visible as
part of a URL.  Include files containing a class should be named
according to the class name (e.g. class WebSite could be named
"WebSite.inc.php").  

As all images are visible as part of a URL, they should be named in
all lowercase as well.  Images should be in either jpeg, gif, or png
format.

There should be no more than one class per file.  There are exceptions
to this rule, for example if there is a utility class that is private
to a particular implementation.  In general, however, if the class is
going to be used in another file, it's preferred to separate it out
into another file by itself.

Any PHP logic code should be well documented.  All classes should
minimally contain documentation on what the expected interface is, as
well as what the public functions are.

Although there are certainly exceptions, classes and objects are
preferred over functions for site logic, within reason.


Code Formatting
---------------

All php and html source code should be formatted according to the
following set of guidelines.  There are plenty of alternative styles,
and for most there are few justifications over what is better beyond
one's personal preference and familiarity.  As such, the following
formatting requirements are imposed to maintain code consistency.

1)  Indents are 2 characters and tabs are at 8 characters.  There
    should be vi and emacs settings in each file to adopt, enforce,
    remind, and encourage this convention.  Suggestions are welcome
    for how to set up this for other environments.  The following
    lines should be included at the very end of all source files:

    <!--
      -- Local Variables: --
      -- mode: sgml --
      -- tab-width: 8 --
      -- c-basic-offset: 2 --
      -- indent-tabs-mode: t --
      -- End: --
      -- ex: shiftwidth=2 tabstop=8 --
      -->

2)  Dead code should not be left to rot, nor should comments not
    related to the actual logic or functionality of the code be left
    in (e.g. <!-- Added by blah --> comments).

3)  HTML code should be run through htmltidy.  PHP code may also be run
    through htmltidy, though it is known to cause problems.  HTML Tidy
    may be obtained via http://tidy.sf.net/.

Violations to the aforementioned rules are not cause to follow suit.
Code that does not conform may be fixed.


@


1.1
log
@initial developer info
@
text
@d1 3
d12 72
a83 1
php code should be well documented.
d85 3
a87 1
classes/objects should be used for logic instead of functions.
d89 2
a90 1
indent php and html, 2 space indent with tab stops at 8 characters.
@

