Benefits of Comments
Making sure that everyone on the team is adding detailed comments can take communication to the next level. So let’s breakdown the benefits of detailed comments and some ways to get your team on board with leaving more detailed comments.
- Detailed comments can help set expectations. If you need more information or need someone else to do something before you can continue, assigning the issue to that person with a detailed explanation of what you need can move things forward much faster.
- Detailed comments can save time. On the surface it might seem that not typing a comment is saving time, but in reality, the real time savings happens when there’s no back-and-forth due to a lack of information. By investing up front in writing a detailed comment, you can eliminate that downtime created by back-and-forth exchanges for clarification.
- Comment history can help manage scope. Have you ever had a client tell you that they thought you agreed to add a requested feature? Or have you ever had a case where they thought you were going to implement something differently? When this happens, it usually boils down to a simple misunderstanding, and having a discussion captured in detail can usually help.
- Comments help answer questions down the road. Why did we decide that? Who decided that? Sound familiar? By capturing decisions and the thought process that led to those decisions, you minimize the amount of second-guessing and flip-flopping that you inevitably do as you dive deeper into problems and their solutions.
Habits for Encouraging Comments
Enough about the benefits. In an ideal world, that would be enough for everyone to want to leave great comments, but sometimes it takes al title motivation to get the team on board. So now let’s look at ways to help support the commenting habit.
- Make it a team standard. Just like you wouldn’t commit code without a comment, it helps to create a team standard and expectation that all issue updates need a detailed comment.
- Record offline conversations in comments. If you have a phone call or even a desk side chat, take a moment and add the key takeaways from that conversation to the relevant issue. Creating this habit, and having the decisions recorded becomes incredibly helpful deciphering decisions down the road.
- Focus on the comment rather than the meta data. Updating meta data is important, but without the comment, the meta data is just an arbitrary change. It’s the explanation and thought process that gives meaning to the meta data. Why are you resolving the issue? Why are you reassigning it? Why are you changing the priority?
- Remember that commit messages don’t automatically make good comments. You can update issues via commit messages, but commit messages don’t usually make great issue comments. However, great issue comments usually provide loads of value as a commit message.
- View comments as a dialogue rather than a task. It’s tempting to just go through the motions of typing a comment for the sake of typing a comment, but if you approach it as a conversation with someone else, it can make it more natural and helpful.
- Don’t think of resolving or closing as the end. Sometimes, resolving or closing an issue feels like you’re done and won’t have to mess with it again, but sometimes issues are reopened or revisited down the road. Think of comments as an archive, not a milestone.
- Help everyone appreciate the value of detailed comments. Sometimes, the simplest tool is the best. Just take the time to explicitly remind your team about the usefulness of comments.
Clear and effective communication is central to issue tracking. Without it, you’re just working through a todo list. Anytime an issue is updated, resolved, or closed, the comments are the best way to communicate intention and desires as well as the best way to create a long-term record of the process and save a lot of pain in the long-run.