-
Notifications
You must be signed in to change notification settings - Fork 187
Developer Notes Suggestions 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.
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
We're not. See below.
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.
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.
See below. This is the a new document, so there aren't many. Now is the time to contribute.
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.
Where we differ, we will try to document it.
Below, you will find some basic rules that have been used so far.
#####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.