-
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
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.
#####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 {
...