# Coding Style

All code generated by the SNAC project will be written in one of the following languages.

* PHP 7 (preferred)
* PHP 5
* Java
* XSLT


## Coding Style Specifications

Source code must match the following style guidelines:

* 4-space tabs with literal spaces
* Maximum line-length of 100 characters
* Variables and Class names follow standard camel casing syntax, with descriptive names
    * Class names start with upper-case letters
    * Variable and field names start with lower-clase letters
    * No underscores allowed in variable names
* Filenames must match the name of the class defined within (exactly)
* Directory structure must mirror the namespace structure (PHP)

## Test-Driven Development

Each class that is written should have matching and appropriate unit tests written.  For PHP code, those tests will be executed using the [PHPUnit](https://phpunit.de/index.html) unit testing framework.

## Internal Documentation of Code

All code will be internally-documented using [Javadoc](http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html) style documentation, which has been ported to PHP as [phpdoc](http://www.phpdoc.org/docs/latest/guides/docblocks.html) and XSLT as [XSLTdoc](http://www.pnp-software.com/XSLTdoc/).  Tools to generate documentation from the code is also available for [Java](http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html), [PHP](http://www.phpdoc.org/), and [XSLT](http://www.pnp-software.com/XSLTdoc/).

* All files, regardless of language,  must have javadoc-style documentation with author attribution, definition of the file, and short-text of the code license, as defined below (in PHP):

    ```php
    <?php
    /**
     * File Description Headline
     *
     * Paragraphs describing the file
     *
     * License:
     * ....
     *
     * @author Robbie Hott
     * @license http://opensource.org/licenses/BSD-3-Clause BSD 3-Clause
     * @copyright 2015 the Rector and Visitors of the University of Virginia, and the Regents of the University of California
     */
    ?>
    ```

* All classes, fields, methods, and function definitions must include documentation, as shown below:

    ```php
    <?php
    /**
     * Name Reconciliation Engine Main Class
     *
     * This class provides the meat of the reconciliation engine. To run the
     * reconciliation engine, create an instance of this class and call the
     * reconcile method.
     *
     * @author Robbie Hott
     */
    class ReconciliationEngine {


        /**
         * Main reconciliation function
         *
         * This function does the reconciliation and returns the top identity from
         * the engine.  Other top identities and their corresponding score vectors
         * may be obtained by other functions within this class.  
         *
         * @param identity $identity The identity to be searched. This identity
         * must be in the proper form
         * @return identity The top identity by the reconciliation
         * engine
         */
        public function reconcile($identity) {
            return $identity;
        }
    }
    ?>
    ```

## Licensing in Github/Gitlab

Each code repository must contain the full BSD 3-Clause license below.  It must be saved in the document root as a text file titled `LICENSE`.

```
Copyright (c) 2015, the Rector and Visitors of the University of Virginia, and
the Regents of the University of California
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice,
this list of conditions and the following disclaimer in the documentation
and/or other materials provided with the distribution.

3. Neither the name of the copyright holder nor the names of its contributors
may be used to endorse or promote products derived from this software without
specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
```
