---
description: >-
  The general style guide provides basic guidelines on how to write code at The
  Orchard, while being language agnostic. Through this document, we will also
  cover different aspects of good engineering pr
---

# Orchard Style Guides

### Language specific style guides

* [api style guide](api.md)
* [css style guide](css.md)
* [html style guide](html.md)
* [javascript style guide](javascript.md)
* [php style guide](php.md)
* [python style guide](python.md)
* [ruby style guide](ruby.md)
* [repo naming style guide](repos.md)

### Documentation

Documentation is essential for any codebase of any size. It helps engineers quickly understand the responsability and scope of each piece of code. Documentation includes: files, classes, methods, functions, and properties.

Some languages \(such as python and php\) utilise those documentations to provide additional context \(through IDE\) or to generate documentation automatically \(sphinx.\)

Do:

```python
def count_activity_failures(events):
    """Count the number of times an activity has failed.

    Args:
        events (dict): list of activity events.
    Return:
        int: The number of times an activity has failed.
    """

    return len([evt for evt in events if evt == ACTIVITY_FAILED])
```

Don't do:

```python
def count_activity_failures(events):
    return len([evt for evt in events if evt == ACTIVITY_FAILED])
```

The lack of documentation makes it unclear what `events` should be.

### Projects

All projects should contain a `README` that contains information on:

* None of the dependency is GPL licensed.
* How to install the application and resolve all the dependencies. If the application has some specific requirements \(e.g. environment variables\) it should be mentioned as well.
* How to run the tests: applications \(regardless of the number of languages they use\) should provide examples on how to run the different test suites.

When setting up a new project, make sure that:

* Tests are running automatically on jenkins on every pull requests. 
* It is private to the organisation \(not available outside of TheOrchard\)
* None of the credentials \(AWS, databases\) are being hardcoded into our 

  codebase.

### Unit-Testing

A good codebase is a codebase that has good test coverage \(above 80%\). It strengthens confidence about consistent code behavior, quickly catches changes that may break production, and makes any refactor a lot easier.

* **How should I prioritize integration tests vs functional tests vs unit tests?** In a perfect world, an application would undergo all three types of testing. For new code, engineers should consider unit tests as MVT \(Minimal Viable Testing - fun new acronym!\). Functional and integration testing can be considered as nice to haves and an engineer should use their judgement on whether it is worth taking the time to add these tests.
* **Is it okay not to not write unit tests for methods if functional tests provide code coverage?** No, even when unit tests feel redundant with existing functional tests, they provide a low level of testing that is invaluable in helping to pinpoint issues. Imagine the years of our lives we could save trying to determine the source of a red build for the Orchard repo given more unit tests! To [plagiarize O'Reilly](http://chimera.labs.oreilly.com/books/1234000000754/ch03.html#_unit_tests_and_how_they_differ_from_functional_tests), "Functional tests should help you build an application with the right functionality, and guarantee you never accidentally break it. Unit tests should help you to write code that’s clean and bug free."
* **How can I test code I've added to some legacy code?** The best way to deal with legacy code is always to not add code in it aside from what's strictly necessary. It depends on the case, but ideally, you would create a new method that will contain the new code, and call this method from the legacy code \(which makes the change minimal, and allow you to unit-test.\)

### Readability

#### Naming convention

Each language has its own rules when it comes to naming convention \(underscore, camelcase\), but in the main lines: always make sure that you properly name your content: names \(classes, properties, methods\) should be readable, short and easy to understand. No giant variable names.

Don't do:

```python
a = House()
a.add(5)
```

Do:

```python
my_house = House()
my_house.add_rooms(5)
```

#### Tabs and Spaces

We only use spaces. Our default is 4 spaces but it may differ for some languages \(or frameworks\). Always refer to the language style guide \(or the file your are currently editing.\)

#### 80 characters

Our default rule follows the PSR2 convention: soft limit at 80 characters and 120 as a hard limit. Always try to remain near 80 characters as it facilitates code-reviews.

### Code reviews

Code that needs to be added to our codebase needs to follow our style guides and needs at least one reviewer \(ideally the system owner or the person which is the most familiar with the code that is being added / changed.\) If the review provides a `R+`, it means you are allowed to merge.

Some advice:

* Write clear titles and descriptions: The title and the description defines the scope of your pull request, it greatly helps the reviewer understand the reasons and the change itself.
* Keep your pull request atomic: only one change at a time, it makes it faster to get your code approved and merged.
* Comments: always acknowledge comments, and always be respectful. If a comment is unclear, just ping the author privately. Always keep in mind that pull requests are never deleted.

### Additional guidelines

* File format: utf-8
* Always have an empty line at end of file

## Contributors

* Christian Tate \(ctate@theorchard.com\)
* Joe Viletto \(jviletto@theorchard.com\)
* Michael Ortali \(mortali@theorchard.com\)