Document Implementation Decisions
| | class Inventory { |
| | |
| | private List<Supply> list = new ArrayList<>(); |
| | |
| | void add(Supply supply) { |
| | list.add(supply); |
| | Collections.sort(list); |
| | } |
| | |
| | boolean isInStock(String name) { |
| » | // fast implementation |
| | return Collections.binarySearch(list, new Supply(name)) != -1; |
| | } |
| | } |
Decisions are what make life hard. They do the same to code.
Sometimes you have to make a hard decision in your code—one where there’s no objective right or wrong, one that has advantages and disadvantages. This is when you need comments!
Consider the code above. Are you wondering why the programmer decided to use a binarySearch? Well, at least he left us a (helpful) comment: it has to be fast.
The programmer made the decision to use binarySearch, but by saying yes to this option, you’re saying no to a lot of other options. Is the comment really a good justification for this? Think about what you would like to know here. And think about what answers the comment gives you.
Here’s what we’d like to know: Why is it fast? Why does the code have to be fast? Is the binarySearch method really fast? What costs or trade-offs does this fast solution cause?
And what does the comment state? Well, obviously there are no answers to these questions. So how could we improve this?
Take a look at the new and extended comment:
| | class Inventory { |
| » | // Keep this list sorted. See isInStock(). |
| | private List<Supply> list = new ArrayList<>(); |
| | |
| | void add(Supply supply) { |
| | list.add(supply); |
| | Collections.sort(list); |
| | } |
| | |
| | boolean isInStock(String name) { |
| | /* |
| » | * In the context of checking availability of supplies by name, |
| | * facing severe performance issues with >1000 supplies |
| | * we decided to use the binary search algorithm |
| | * to achieve item retrieval within 1 second, |
| | * accepting that we must keep the supplies sorted. |
| | */ |
| | return Collections.binarySearch(list, new Supply(name)) != -1; |
| | } |
| | } |
Now that comment is a lot more informative. It states the use case, concerns, the solution, and also any trade-offs or costs we have to pay.
The comment isn’t just more helpful now. It’s also easy to write. We simply used a template[25] and filled in the necessary bits. Take a look at it:
| | In the context of [USE CASE], |
| | facing [CONCERN] |
| | we decided for [OPTION] |
| | to achieve [QUALITY], |
| | accepting [DOWNSIDE]. |
You can easily spot this structure and find it in this code. With such a template, you’re less likely to forget important aspects. What’s more, it’s going to be easier for your fellow developers to understand comments that follow a clear and predefined structure. This is a point where team conventions pay off.
Our tip: Use this template for documenting important decisions or tricky parts of your code. It needn’t be exactly the one you see here, but convention helps. So the first time you bump into this in a project, have a team meeting and decide on your project template! And be sure to mark affected places in your code as well, just as we did with the comment for the list field.