Although it might be tempting to quickly file a ticket that will scope multiple work segments and give it a short description (that is clear to you and maybe a few teammates), later such tasks may affect negatively on the entire team’s productivity.
Divide Et Impera
Here’s a blogpost from guys who do project management tools for living, on why it’s important to properly size the task and break it into smaller chunks.
A summarized list of reasons:
- You can’t remember everything. So while working on big pieces of work sometimes it’s easy to lose focus and accidentally skip something important.
- Smaller tasks are way easier to estimate and describe clearly.
- Smaller tasks produces less code that is easier to review effectively. Also frequent feedbacks help us to keep ourselves on a right track and improve implementation in the fly.
- Completing a task feels good. The more often your work is delivered, the more often your brain releases dopamine.
Imagine working on some food delivery service and creating a task like “Implement ‘become a deliverer’ flow on front-end”. It might be worth breaking it down into pieces like:
- “Create base UI components”
- “Extend front-end services with ‘become deliverer’ flow API calls with unit tests”
- “Implement ‘Personal Info’ step layout with Cypress tests”
- “Implement ‘Transport’ step …”
- …
It is also a good practice to create SPIKE tickets if you feel uncertain of possible implementation ways. Investigation results are good to be discussed with team members afterwards.
Reasonable Ticket Structure
Here’s a list of things that speed up developer’s understanding of the problem ×100 times:
- Acceptance criteria – an answer to a question “What should we have/know/be able to do when work on this task is done?”.
- Clear steps to reproduce the issue if it’s a bug-fix ticket (imagine yourself reproducing it at app’s initial state).
- Screenshots/GIFs/video attachments of known front-end bugs.
- If you have any guesses where the bug might be fixed, post this info in ticket description.
- Links to designs really come in handy for layout implementation tasks.
- Links to open/merged PRs, that would help quickly find code of changes you made.
- What the motivation is. Explain the problem that you want to solve and when appropriate, present your idea for a solution to the problem but leave room for discussion or alternate approaches.
How About Pull Requests?
Main purpose of a PR is not just to merge your changes into master, but to give other people a good understanding of your work’s context and reasons behind your changes. Perception of all that stuff is way easier when reviewing a short PR that scopes some single logical concept (or at least not too many of them).
Short PRs are good because they:
- Speed up code review process and consequently the product development.
- Reduce bugs introduction into codebase.
- Don’t block other developers and reduce chances of conflicts between branches.
When reading through your finished work try asking yourself “Will other people easily understand what and why is happening here? Will they not lose focus and understand all the connections between changes made?”.
If not, there’s absolutely nothing wrong with breaking your PR into bunch of smaller ones that would be easier to digest.
A couple of great ways to make PRs enjoyable to read through:
- Add a link to the ticket where changes are requested.
- Give it a sufficient description of what changes were made to achieve requested result.
- Add screenshots, GIFs or videos of layout implementation results.
- Provide steps for local testing, if appropriate.
- Add comments to your code that you expect to be unclear for others for some reason (although of course we aim to write self-descriptive code needing no explanations).
Cheers!