Developer Notes Suggestions Guidelines

What is this about guidelines?

It seems prudent to set some guidelines for contributions to this project. There are many good reasons for having a consistent style in an application, and these are covered in many other locations.

But really, why?

See above, but as a short list:

• makes code easier to undertstand for new developers
• makes code easier to maintain for long-term developers
• makes contributions easier to integrate for everyone
• (in theory) the guidelines should encourage good coding styles

OK, but why re-invent the wheel?

We're not. See below.

What if I don't conform?

If you don't it makes it harder for us to read your code, and harder for us to maintain your code. The result: it is less likely your contribution will be used.

If your contribution is so good that we use it anyway, we will probably restructure it ourselves, or be slower to maintain it. This reduces the time we have to add our own features, so the project suffers overall.

The guidelines suck, they should be changed!

Great! We welcome useful critiques on the guidelines. Tell us why they are wrong, and tell use what we should change, and why the change makes it better.

OK, so what are the guidelines?

See below. This is the a new document, so there aren't many. Now is the time to contribute.

Guidelines

We are Borg.

Basic rule: conformity is good. If existing code handles common tasks in a standard way, please try to do them the same way. If you think the way we do it is bad, tell us. We might change. Change is good.

See the Android coding standards for a good starting point re Android, and the Sun/Oracle java style for a more general Java style guide.

Where we differ, we will try to document it.

Below, you will find some basic rules that have been used so far.

Simple stuff

---

#####Use brackets always in if..then...else

Example:

if (a == b) {
   c = 1;
} else {
   c = a/b;
}

Exemption if its if <condition> \n return, but even then brackets are cool.

---

#####Javadoc is good. Use javadoc comments.

Example:

/**
 * Request authorization from the current user by going to the OAuth web page.
 * 
 * @author Philip Warner
 * @throws NetworkException 
 */
public void requestAuthorization(Context ctx) throws NetworkException {
...

---

#####Readability trumps brevity. Every time.

Bad:

  if( (i = next()) < count ) {
      ...do stuff...
  }

OK:

  i = next();
  if ( i < count ) {
      ...do stuff...
  }

---

#####The code is the documentation. If you rely on defaults, make them explicit.

Example:

<LinearLayout
    ....
    android:orientation="horizontal"
    ....

Don't rely on other developers having your intricate knowledge of the current API. Don't rely on yourself having that knowledge in 2 years time.