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 ?
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.
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.
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.
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 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! ?