Coding Specifications.md 4.81 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20
# 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
21 22
* Filenames must match the name of the class defined within (exactly)
* Directory structure must mirror the namespace structure (PHP)
23

24 25 26 27
## 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.

28 29
## Internal Documentation of Code

Robbie Hott committed
30
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/).
31

Robbie Hott committed
32
* 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):
33

34
    ```php
35
    <?php
Robbie Hott committed
36 37 38 39
    /**
     * File Description Headline
     *
     * Paragraphs describing the file
40
     *
Robbie Hott committed
41 42 43 44
     * License:
     * ....
     *
     * @author Robbie Hott
45 46
     * @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
Robbie Hott committed
47
     */
48
    ?>
Robbie Hott committed
49
    ```
50

Robbie Hott committed
51
* All classes, fields, methods, and function definitions must include documentation, as shown below:
52

53
    ```php
54
    <?php
Robbie Hott committed
55 56 57 58 59 60 61 62 63 64
    /**
     * 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 {
65

66

Robbie Hott committed
67 68 69 70 71 72 73
        /**
         * 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.  
         *
74 75
         * @param identity $identity The identity to be searched. This identity
         * must be in the proper form
Robbie Hott committed
76 77 78 79
         * @return identity The top identity by the reconciliation
         * engine
         */
        public function reconcile($identity) {
Robbie Hott committed
80 81 82
            return $identity;
        }
    }
83
    ?>
Robbie Hott committed
84
    ```
85 86 87 88 89 90 91

## 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
92
the Regents of the University of California
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
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.
```