Contributions and Code Conventions

OTP is developed by a large group of people around the world. In order to ensure that we can readily understand one another's code and that people will be able to properly maintain the code in the future, we require all OTP contributions to adhere to some guidelines.

Contributing

Commits should reference tickets.

Pull requests should have comments explaining what they contain. After you've been hacking on something for a week, it's easy to forget that many other contributors (including the person reviewing your patch) may not have seen this particular corner of the codebase for many months.

It's good to have a bit of clarification in the commit message itself (starting on the third line), and/or in the pull request comments. But best of all is to put enlightening comments/Javadoc directly in the code.

Comments

All new non-trivial methods must be accompanied by substantial comments. Even if someone could figure out the purpose and function of your code by studying it carefully, we don't want to impose that burden on every person who needs to understand it in the future. In terms of total developer effort, it is much more efficient for the person who wrote the code to document it.

By substantial comments, we mean that the comments must give information beyond what is superficially visible in the code (context, algorithms, references to bug reports). For example, the following Javadoc block should be replaced with a more detailed explanation:

/**
 * Process some data.
 *
 * @param data
 */
 private void processData (String data) {

Unfortunately there is a lot of undocumented code still around. If you come across some and spend a while deciphering it, please don't hesitate to add Javadoc or other comments and contribute them via a pull request.

Maintenance branches

Whenever we tag a release (e.g. opentripplanner-0.11.0) we create an accompanying maintenance branch (in this case, 0.11.x). These maintenance branches will receive only critical bugfixes, and all development of new features will be done on the master branch. While you may choose to use these release tags and maintenance branches as stable snapshots for production systems, any pull requests you submit against them for new features will probably not be merged into the main OTP repository. Given the size of our team, we need to avoid the extra maintenance effort and cognitive load of parallel development paths.

Line widths

This is another arbitrary style issue where consistency matters more than the exact rule chosen. Monitors are wide these days and no one's using lineprinters, but many people find narrow lines easier to read and some people like to keep several files or IDE panes side by side. Therefore, try to limit line widths to 100 characters, but don't hesitate to go a few characters over to improve layout or readability.