Conventions

Or how to communicate in a team

As soon as more than one developer is working on a project you are in trouble. Communication is 100% of a developers work. We communicate with our words (in meetings, one-to-one, chat, etc.), body language and even with our code. The interesting part about this is we communicate an intent and not the words itself. It's proven for the receiver to decide on the meaning of a message and not the transmitter. Thus we have to do our best to make sure the receiving end will understand the intent we are trying to transmit. One option improving the communication is via conventions. They help in a lot of different ways, but most often just by having the same meaning in the same situation. Starting on a different project? In case the structure has a convention, you'll find access way faster. Conveying changes to functionality, using the same terminology helps. In this post we will look at a few types of conventions, which will be part of your everyday life.

Code Conventions

Everyone heard of code conventions. They help developers to find their way into projects or understand the code faster. If everything is written in the same style, suddenly it's not so different to the code you read before, or the code you wrote yesterday. There are so many different code conventions and opinions, so I won't suggest a specific one. Just chose one and stick to it. Make sure everyone on the team adheres to them.

The best way to do this is by using an auto formatter. Concerning Swift there is swiftformat. Sadly it does not have a config file yet and has to be started via command line parameters. But it works quite nicely.

Another tool to enforce code conventions is swiftlint. It has only a few auto format options, but it offers other interesting configurations to enforce one style of code.

Commit Conventions

Making sure not to lose any code and ensure working in teams we are using version control systems. These tools try to limit errors by either locking files for changes, or displaying merge conflicts, in case multiple developers changed the same file. Submitting our code we leave a message for other developers to understand in a fast way, what we did, without him having to read the changes is code. Commit messages are more important than most developers think. If you've searched for a change for a few hours you will appreciate a well structured and meaningful commit message. As there are once again a bazillion different conventions for commit messages I shouldn't recommend one. But I tend to use this:

<Ticket> <Type>: <summary in present tense>

This seems to contain some overhead, and colleagues of mine despise information like the type of change. But let's have a closer look to what I'm proposing.

Ticket: This is the name of the ticket this change affects. It does not have to be the only change for this ticket, but if we are looking up, what precisely the requirements were, we need the ticket.

Type: I like knowing whether this change was due to a feature, a bugfix, some kind of necessary work, or any other reason. You can find some suggestions for types at the Angular Commit Message Format. Quite a few people might raise concerns regarding the type being misleading. This would be the case, in case the developer is not separating his commits. In my opinion this can even help to teach him to do so.

Summary: This contains the intent of the change, not the precise changes the developer did. So instead of writing "Added some files and changed it to do this or that" you should write "This adds feature 1" or "This fixes the crash after logout". Using this kind of message, will improve communicating your intent.

Conclusion

As you can see, there are a lot of ways to improve our communication via conventions. A clear intent goes a long way. For our project we will stick to the code conventions swiftlint suggests by default. Furthermore the above commit message format will be used.

Next: Git Hooks

Previous: The developers machine