Coding Style and Standards Guidelines - swansond/LavatoryLocator GitHub Wiki

Coding Standards

Our code reviews are all done on GitHub, via the Pull Request functionality.

Developers will all work on branches for whatever functionality they are working on; when the developer is done with some feature or simply wants a review of what he has done so far, they will submit a pull request to the parent branch (be it master or some other branch), and the other team members are notified.

Developers should generally never push directly to the master branch, as this essentially bypasses the code review process, but this is a soft rule for our server code (LavatoryLocatorDB) as we need to push to master in order to deploy any changes and test what we have done; quick edits are permissible in this case, but anything larger than one or two lines needs a pull request.

At least one other member of the group will look it over and comment as necessary on both style and correctness; this will typically be the pull requester's partner (in their subgroup). Comments can take the form of both line comments or comments on the pull request itself.

Because reviews only need at least one reviewer, each review will need to be holistic, covering the source code's style (whether it follows the guidelines we have defined below), correctness, and maybe efficiency, if relevant.

The reviewer will either merge the branch or indicate that it would be okay/not okay to merge, and the original pull requester can act accordingly.

In order to ensure coding style is followed, David Jung will go over the code make sure that all written code follows the given style guidelines.

Java Style

We will follow Oracle's Java Code Conventions, but with some modifications:

  • We will use four spaces for an indent, and on line breaks inside of method invocations, headers, etc. use an eight-space indent.
  • We do not require a blank line before every single-line comment.
  • Strict boolean zen.
  • Javadoc:
    • For each public method, use javadoc.
    • Javadoc needs to include @return, @param, @throws, and optionally @requires, @effects, @post.

PHP Style

This is for our second repository, LavatoryLocatorDB. We will generally follow the Zend Framework Coding Standards for PHP, but again with some caveats:

  • The guide assumes that the reader is writing code for the Zend framework, but we're writing web services, so we're lenient about having things be in global scope and a general lack of classes.
  • Constants must be defined in all caps and with underscores, but they can be simple variables instead of actual php constants (defined with the define function or otherwise).
  • For file headers we only require a short description of the file and an @author tag (no license information and other "javadoc" tags).
  • Close parens and braces will be on the same line as the last line of the expression, e.g. class Foobar {, if (cond) {.