May we suggest...

Introducing Android code style guidelines at Buffer

Whenever you’re working solo on a project, chances are you’re writing in ‘your’ style – which often makes it easy to make all your code look and feel the same (but not necessarily clean). And when there’s more than one team member contributing to a project, it can be difficult to ensure that code is kept both clean and readable. Chances are that everyone has their own way of doing something, even when it comes down to things such as the way variables are named or the ordering of methods within a class – these may be small differences but they can quickly build up. The problem is, when code style differs between files it can cause a number of different problems. For example, it can take you longer to navigate through files when there is no organisation of methods, or it may take you longer to make amends to a class because you’re trying to stick to a style that you are not familiar so you can try to keep the code in there clean. And as a team grows, new developers could be writing code in another different style – the difference grows even more and the issues caused by unclean code grows more and more, in turn affecting things such as readability, consistency and more.

For a number of reasons, we’ve decided to document our new code style for our Android App at Buffer. All new code that we write will be written in this new style, with any backtracking being done as we refactor and re-implement features. These guidelines are about being mindful of both the projects health and your team members. They are not designed to be static – we will most definitely add to them, as well as return to certain areas that we may want to rethink ?

Consistent

Consistency compliments all of the points in this list, without consistency all of these would suffer. Having guidelines allows our applications code-base to remain consistent during the development process. We can move between files and know that the both the look and feel of code is going to remain the same, regardless of who may have worked on it – no matter how far along the line in time.

Readable

These guidelines allow us to help ensure that our code remains readable, regardless of who may be developing on it. Readable code reduces cognitive load for the reader, rather than taking the time to decipher what a method name says, what a parameter is used for or what the variable ‘xyz’ is used for – we can get straight to concentrating on the task at hand. Again, the codes readability is again affected by the other points made within this list.

Maintainable

Having guidelines helps make it easier to both fix issues and add new features. Not only will we be more familiar with the structure and organisation of the code we may have not worked on, but we’ll also be creating code that will create the sense of maintainability for the other members on our team. These guidelines also help us to encourage the decoupling of responsibilities amongst classes, allowing us to both re-use components and reduce the complexity of others.

Navigable

The time spent trying to find classes, methods or variables can quickly rack up if there are no conventions in place. And as a project grows, it can become harder to navigate around the files, especially for new team members who may join. Having guidelines in place can help our projects structure and files to become more navigable, this can be achieved by a combination of naming and ordering for files, methods and variables. Knowing that the interface will be located at the bottom of the class saves me having to scroll through the class file, knowing that the class is ordered by lifecycle methods allows me to quickly find the onDestroy method and using the method name searchUserId instead of findUserId for a search method makes it quicker to find when using my IDEs search functionality.

Meaningful

Meaningful code is both simpler and clearer, making it easier to understand what it is our code is meant to be doing. Variables should mean what they’re named, methods should only do what their name tells us and a class should be used for what its name entitles.

Saying that, I think it’s about time you took at look at our guidelines! We’d love to know what you think of our guidelines or if you’re using them in your own projects! ?

I’m an Android Engineer and I love creating beautiful, clean and functional applications that help to make peoples lives easier – I love to be constantly learning and I enjoy writing about Android things / working on open-source projects over on GitHub. I have a bit of a love for Android TV which I sometimes talk about at conferences too! I first found my passion for Android whilst I was at university and have been working with it non-stop since – I find it an amazing platform. I love how it’s constantly evolving, it’s open-ness and the community around it!

Great to see this article and a big long guide but where is the formatter jar? In my project I set up 80% of these guidlines and then export the jar of my settings and put it in the root of the github project along with a readme.md that screams “IMPORT THE FORMATTER AND INSPECTION PROFILE”(also the macro for when you save, it rearranges/reformats/optimises imports) and then make sure they all get run on every commit for VCS changed file scope. Also you can throw the entire project through it so you at least get every unused import and other items of that scale eradicated also everything gets ordered correctly which just makes me happy.
Just noticed the checkstyle/pmd/findbugs and though I am no expert on them it doesn’t look as though your rules are declared in them as stringently as they could be. Still curious to see the settings jar

Rom Shiri

It’s great, thanks!
Do you have any tool/formatter to force these guidelines you’ve integrate in your IDE (Android Studio)?

Thank you for sharing this, but I would advise against adopting this set of practices (or, at least, cherry-pick just a subset of them). The reason for my suggestion is that I think the following are counter-productive:

1) “Private, non-static field names should not start with m” – this practice suggests that you don’t read your code outside IDE much, otherwise you wouldn’t recommend this. Pull/merge requests reviews outside IDE become much easier when all object’s fields are designated by “m” prefix (explicitly shows variable’s scope). Furthermore, “m” prefix is used in AOSP’s code, therefore it is de-facto standard for Android.

2) Section 2.2.14 suggests usage of Log statements “guarded” by build type check. First of all you should not use Log statements in your app, but delegate to some non-static wrapper which you can mock for unit testing (I guess you don’t unit test your code, or test only with Robolectric, right?). Secondly, you should use Proguard and automatic scripts in order to remove logs from the code, instead of polluting it with these build type checks.

I didn’t read any further, therefore I can’t comment on anything following section 2.2.14

Sveta Sm

MVP (Minimum viable product) is the first live version of your product that is released on market.
Why you need MVP:
Saves your money from waste
Reduces risks
Opens communication with target audience
Thunderrise is expert in development of MVPs for startups.
thunderrise.com