Even though the stereotype goes against that, developers tend to be social creatures — at least to the extent of (having to?) work in a team. That could be a work team that sits in the same room (or building), a couple of friends that have big ideas and work on the next big thing, or the community of contributors to an open source project. When new developers are added to the team, be it remote, or joining on the desk next to you, there is always the problem of onboarding them.
UPDATE there is a follow-up here, see what lessons I learned in the year since I’ve started committing the IDE project settings to VCS.
The onboarding problem is particularly tricky for OSS projects in which contributors rarely have a process of onboarding. An imperfect solution is to provide a CONTRIBUTING file that shows a notice when you open a PR on GitHub.
The problem is, as with all readmes and documentation, there’s always people that doesn’t read it or misinterprets it. As with everything that involves coordinating a bunch of humans to follow conventions, the best way out is to:
Automate the hell out of it!
Define the rules
As you certainly know, the IDE allows you to reformat code following certain rules. Now, in general it is discouraged to enforce IDE lock-in, but at least for Android, you can safely assume everybody is using Android Studio and Gradle to develop. And if they’re not, it’s a good time to delete that Eclipse install and have them join what people has been doing in #AndroidDev, circa 2014.
The IDE can help you by providing default file templates, live templates, that will minimise the risk of people not following your conventions. Don’t like Hungarian notation? Remove the m field prefix from the suggestions. Think that attribution headers have no room in a world where code is under VCS? Edit the file template for new classes. Think four spaces is the way to go? Well, as you have guessed, the answer here and for all other answers is, enforce them in the code style settings.
That’s great! Now every time you hit cmd-alt-l to invoke Reformat code (or ctrl-alt-l on Windows and Linux), your code will be tidied up to match the style conventions as much as possible. But that won’t be true for everyone else, as the rules are only on your local default profile.
So how do we put our rules out there?
The shared jar of rules
In Novoda we try to solve the problem by providing an IDEA/AS settings JAR. That JAR contains all the rules and settings we share across the company for Android development. We have every new Android developer grab that and import the settings, and that mostly does it. When a need arises to change the rules, a PR is issued and reviewed/discussed by our developers.
This solution doesn’t take into account two things, though. One, that different projects can have slightly different conventions. For example, a project team might be hell-bent on putting final everywhere they can, where the rest of the company has a more nuanced approach. The second problem is that there is no way to keep everyone consistently up to date with convention tweaks, short of having them pull the JAR manually. But there is no way to enforce it, and someone might simply miss the announcements of new rules.
Yes! We can do more than this!
The journey to find The Right Way™
A few months ago, I conducted some research on how the IDE settings could be shared among my project’s developers. We have had a bunch of turnovers in the team, and a bunch of new hires that came to pair, and we needed to have everyone on the same page. On top of that, the project has some unique stylistic conventions that aren’t in the company-wide settings, so the Novoda JAR wasn’t enough for us.
Let’s quickly look at the avenues I have explored.
Building on top of the shared JAR solution
A former colleague, Conor, contributed a script that packages a JAR file starting from the settings XML files that it contains. That solves the big issue of the JAR itself — there is no diff when you do a PR, and you can’t merge changes across sources. That could’ve possibly worked, but would have required someone to merge in the changes from the Novoda guidelines into the project’s manually, from XML, where the values of the properties aren’t always clear. Too much risk of human error.
Built-in settings repository
There is a feature of IDEA and AS, called Settings Repository, that looks quite interesting. On paper, it allows you to sync your IDE settings with a specific repository and sync them across installs. The problem I found here was that this would share all your settings, including usernames for services, etc. The lack of customizability and control over how and when the sync happened led me to pass on this one as well.
Putting the IDE settings file into VCS
I’ve looked at several alternatives, but ended up sharing part of the .idea configuration folder in git. It’s common practice, and good norm, to exclude it from VCS along with .iml files and others, but in this case, we had a good reason.
JetBrains provides a very convenient list of files you should never put under VCS in the .idea folder. The rest is safe to put under version control! We’ve been doing this for a few months, and we’ve never had any issues after the first couple of weeks, when we were still figuring out how to do it properly.
Let’s get this sharefest started!
Sync Project settings using VCS
The first step is to remove the .idea folder as a whole from the VCS exclusions and add more fine-grained rules. Most people use Git, so that’s what the examples will be using. In your root .gitignore file, make sure you don’t have an entry that looks like this:
/.idea/*Applying all the JetBrains’ recommendations from before, and after some battle-testing, I ended up with this set of rules for the .gitignore that seems to cover all our needs (and more!):
# IDEA/Android Studio Ignore exceptions
!/.idea/vcs.xml
!/.idea/fileTemplates/
!/.idea/inspectionProfiles/
!/.idea/scopes/
!/.idea/codeStyleSettings.xml
!/.idea/encodings.xml
!/.idea/copyright/
!/.idea/compiler.xmlCommit that. Now, open the preferences ( Cmd-` on a Mac, Ctrl-Alt-S elsewhere), and navigate to the Code style section. Then click the Manage button:
In the dialog that opens, pick the scheme to use as a base — it will be Default unless you have something like Novoda’s shared scheme — and click Copy to Project.
Congratulations! Now you have a bunch of “new” files in your .idea folder. Those files have rather self-explainatory names. The most important ones are of course codeStyleSettings.xml and the contents of fileTemplates. Note that these files/folders will only appear when your settings are different from the default schema’s.
That’s really all you need to do. Once you commit them, everyone that picks them up should be up and running with the shared settings. Anything that shows up in the preferences screen and in other places with the small icon that looks like a copy icon (two overlapping sheets of paper) can be part of the shared settings:
A couple of caveats
You might want to check that people isn’t using overridden settings themselves, when you first roll the project settings out. In that case, the IDE might override the settings coming from VCS. I’m not sure this is intended behaviour — it seems weird to me, but it’s easy enough to check.
Another small note is that you want to keep your additional plugins in check. Some plugins tend to write their own settings, and that should be fine, but the problem is that a bug (marked as resolved, but it’s probably a regression) in the IDE causes “unknown” code style nodes to be removed instead of ignored. This means you have to make sure the team is aligned on which plugins to have enabled in the IDE while working on the project.
Want to read more?
You can take a look at the other posts in this series.
