Guidelines for friendly programming

Development Handbook.md

Development Handbook

Principles

1. Your first priority is writing code that it is understandable and clearly communicates purpose, intent, and organization. Your second is making sure it is working properly.
2. Always strive to uphold the following priciples: - principle of least astonishment - principle of least knowledge - principle of least access - single responsibility principle

Workflow

1. Once a project is at a point where others are testing it, all non-trivial work should be done in a feature branch that is created immediately and pusehd to regularly.
2. This feature branch should immediately get a Pull Request even if the work isn't finished - just tag it work in progress.
3. When it's ready, mark it ready for review or ready for deploy (depending on whether another dev has reviewed it or if it's a quick bugfix)
4. All merges to master are performed by the project lead
5. All production deploys of the SaaS app should be to a taggged release.

Project Structure

1. All dependencies should be handed in top down
2. In general, exports from modules should be objects
3. In general, use prototypes or classes rather than object literals.
4. Try to stick to one class per file, with the filename matching the class name
5. Configuration should be performed using a yaml file, ideally with important or commonly used flags also available via cli parameters and environment variables.
6. A module should usually be a class that takes options in its constructor and most dependencies should be organized in a tree beneath that class
7. Starting and bootrapping: - Modules providing a service should always be launchable from a script with an appropriate #! in the bin folder named for the module in the bin folder - If possible modules should ship with a sane default configuration, if possible we should strive for having a functional service just by running npm install && npm start

Coding Guildelines

7. Short functions tend to be easier to read, debug, and test. Functions longer than 15 lines should be avoided, the shorter the better and anything over 20 lines needs to be defended
8. Generators should be used for iteration and the like, not async control flow
9. Modules should never write data to a directory without providing a config option to change the directory
10. A module's HTTP API should always be documented using curl examples in the README
11. Modules should have near complete testing from day 1
12. When deciding between more code that's more explicit and less code that's less explicit, choose more
13. A module should export a clean API that it's starting script consumes (e.g. export a Server class with a start() method - then run var server = new Server(options) server.start() from the script
14. All projects should adhere to our coding standards eslint
15. Processes should name themselves appropriately for ease in identifying themselves using linux commands like lsof
16. Comments should say why code is doing something, not what it is doing unless it is really unclear. If it is really unclear, see if you can make it clearer
17. Prefer more structured APIs, less exposed data structures.
18. All new development should have mocha tests, using TDD to iterate if at all possible.
19. Public repositories should integrate with coveralls to report on code coverage if at all possible (for javascript istanbul should be easy to integrate)