How Our Engineers Collaborate
There’s no “I” in “iOS”...wait
Collectively, the engineers at Lickability have worked with dozens of iOS development teams, shipping countless features, new products, redesigns, and Swift rewrites. Ten years in, our processes have evolved into a well-oiled machine with collaboration at the core of our day-to-day engineering. Whether we’re augmenting a client’s existing iOS team or acting as the sole developers, and whether we’re building a social network, news reader, or game, our approach to collaborating on code remains largely the same. We find it important to follow a few key guidelines on every product we help ship, and would like to share them with you.
The 30 Minute Rule
Have you ever been stuck trying to fix a bug that seemed extremely straightforward? Have you ever been knee-deep into a new feature, only to find that something just isn’t working correctly and you’re not sure why? Have you ever felt paralyzed while trying to architect a large feature or refactor, spinning your wheels because you’re not sure if you’re making the right decisions? Of course you have! We’ve all been there, and we’ll be there again. In situations like this, we reach for the 30 Minute Rule.
Have you spent 30 minutes trying to solve the problem with no visible progress, and are you able to describe what you’ve tried and what happened? If the answer is yes, then it’s time to ask a teammate for help. If you keep spinning your wheels for hours and hours, you might be wasting your own time. If you haven’t done your 30 minutes of due diligence before reaching out to others, you might be prematurely interrupting and wasting their time. Our magic number is 30, but feel free to experiment and see what works best for your team.
Frequently asking for help might be hard at first, especially if you’re on a team that hasn’t established a pattern of assisting each other in this way. It can be extremely difficult to fight through self-doubt or imposter syndrome and admit that you can’t proceed quickly without aid. I know. I’ve been there. It’s not just you. But asking someone for help doesn’t make you less-than. After all, you’re a team working toward the same goal, not competing against one another.
Be sure to pay it forward when you can, and reach out to others when they appear halted. It might be that one weird UIKit issue that you know exactly how to work around. They might just need to talk through their approach to make sure it’s not too off-the-wall. Or they might find comfort in the fact that there’s not an obvious, simple solution, and it’s not just them. Once your teammates become comfortable asking for help and assisting each other regularly, productivity will soar and you’ll be shipping with confidence.
Talk Before You Code
Sure, sometimes you can just sit down in front of your computer, read a feature or bug description, and hit the ground running. But for larger or more complicated tasks, it can be invaluable to discuss your path forward with another member of your team. Whether or not you prefer to pair program, talking over architecture, or proposing a solution on a whiteboard before you write a line of code can help to shake out any uncertainties, expose previously unconsidered cases, and give your team the opportunity to weigh in and reduce complexity long before opening a pull request.
You might worry that others on your team don’t have enough context to help at this stage. After all, only you have dug deep into this problem. Ignore those thoughts! Like you, the engineers on your team have diverse experience and have likely helped solve similar problems in the past. Just prepare your thoughts, quickly bring them up to speed about the task, and summarize your approach. At Lickability, we do this All. The. Time. And most of us aren’t even working on the same project! Keep things high level at this stage, and your fellow engineers should be able to help you out.
Make Your Work Easy to Review
Code review is an extremely important part of working on a software team. It provides the opportunity for feedback, collaboration, and an early line of defense against issues entering your shipping software. Some find that code review is a chore, but it doesn’t have to be.
Small Pull Requests
Long running branches are a recipe for disaster and conflicts, full-stop. Many teams don’t need to be sold on the benefits of continuous integration, and with modern tools like fastlane and Bitrise, a lot of the boilerplate work can easily be automated. But no software is going to force you to integrate early and often, and no one wants to review your 10,000 line pull request. Have you ever submitted a gigantic pull request and received one comment, “LGTM”? This is not the feedback you want. Have you ever submitted a gigantic pull request and it just sat there, rotting at the bottom of the PR list, surrounded by other large pull requests that were also increasing in the number of conflicts with main? This is surprisingly common, and we try to do everything we can to prevent it.
Now, have you ever fixed a small bug, or introduced a small new feature, and received 16 comments with helpful suggestions? It’s not a coincidence that the size of the pull request produced different results from your peers.
The optimal pull request size will differ for every team, but at Lickability, we encourage engineers to keep them small (500 lines changed or less), and to the point. Sure, sometimes they end up slightly larger, but we try to minimize that by following these guidelines:
- Don’t fix 8 bugs in one pull request. Fix 1.
- Keep things that generate a lot of noise in code review, like pod updates and adding assets, in their own, separate pull requests that precede the work that requires them.
- If you’re working on a large feature, break it up into many small chunks, and submit your work whenever you complete one. Use any form of feature flagging to integrate these chunks while preventing the exposure of incomplete features to users.
- Try not to go more than a day or two before putting your work up for review. Just because your changes are small doesn’t mean they weren’t difficult or time consuming to produce. The earlier you receive feedback, the less married to that solution you’ll be. It can be hard to accept criticism on something you’ve poured a ton of time into.
You’ll be surprised how much more meaningful your code reviews will be when your pull requests are small and numerous. Someone can review and fully understand your work in the few minutes before a meeting instead of needing to set aside an afternoon of head scratching.
Explain Your Work
I could go on for hours about the value of documenting your code, but even when code is properly documented, it can be difficult to wrap your head around why a change is being introduced, or how it impacts the user experience. We rely heavily on pull request templates to ensure engineers provide enough information to ensure a speedy and easy review. (You can find ours here.)
Whether or not you use a template, we believe a pull request description should contain:
- A link to the issue or task in your issue tracking system so that the reviewer can understand why the change is being proposed.
- A short summary of the approach taken to fix the issue or implement the feature.
- Detailed steps on how to test the change. This will help the reviewer test the feature themselves if they choose to, but also give them the opportunity to see how you tested the feature, and suggest any gaps or edge cases you might’ve missed.
- A screenshot, gif, or video of the change in action, if it has an effect on the user experience.
Here are a few examples from our open-source library PinpointKit.
Teamwork == Dreamwork
If you’ve been writing software for a while, and prefer to work alone, or have been affected by any of the problems discussed here, I encourage you to give some of these guidelines a shot. You don’t have to go all in at once and completely change your workflows. You don’t need the world’s most advanced server-configurable feature flagging system to get started with small PRs. And most of all, you have no reason to feel badly or inadequate if you ask for help. If you’re fortunate enough to work with a team of talented engineers, make the most of it. You and your teammates can do amazing things together.