The importance of writing brief documents when collaborating in projects
Context
I was recently working on a project with a colleague who worked at a different location. I was tasked to improve the translations of the application.
I copied pasted most codes from another ongoing project that had already implemented this service. Apart from a few hiccups, everything worked as expected.
I experimented a few times with some patterns to adopt to know which language the user had currently selected.
I had three choices :
1. For each module, request the user language through an api call.
2. Keep a global logged in user object in local storage.
3. Keep the user language on local storage.
For each module, request the user language through an api call.
This one looks a good option as the user will always get the latest selected language. However, the person won’t be changing his or her language every now and often. The latter will most probably be doing it during setup or update once or twice later.
For such seldom events, it’s expensive to make an API call for each module as the data would most probably not change.
Keep a global logged in user object in local storage.
The app is currently managing authentication by saving the logged user object in local storage and destroying it when logged out. The user’s token is then used in each API call request to the server.
As the language is also stored in this object, it can be used for the translation service. However, if the user does update his or her language preference, no change will be reflected until the latter is logged back in.
To modify the code to update the user object in local storage will break existing behaviour. And I will have to test all use cases covered again.
Keep the user language on local storage.
The 80% solution that requires only 20% effort is saving the user language in local storage. On logging, when retrieving the object, a key value pair for the language is also stored and referenced throughout the application for the translation.
No need for unnecessary API calls and having to refactor the authorisation behaviour.
And when the user does update the language, it is also updated in local storage and the change is reflected throughout the app.
Communication
Having decided, implemented the codes and pushed the changes on the branch, I continued doing other tasks without communicating them to my colleague.
Upon reading the codes and making some modifications, he changed certain part of the codes before eventually asking me why I had use local storage as a medium for storing the translation language. For him, it did not make sense. For me as well it would have been the case until I tried all three ways to cover maximum scenarios with minimum effort.
Using the global user object was enough.
He had already changed the code and pushed on master.
Result
Once I explained to him the rationale behind my choice on Slack, he reverted it before pushing back on master. But he lost at least 2 hours of productive time. From a lean perspective, that was a waste of effort. If I had written a concise document briefly explaining my decision, we would have avoided this situation.
Now let’s assume, in the future, another colleague works on the translation feature. He or she finds that having another local storage variable seems to be redundant and proceed to waste time and effort changing the values.
This effort itself can be mitigated for everyone with the document especially if one day for example, I am no longer at the same company.
Additionally if the behaviour is indeed worth improving, that’s another situation. By updating the document to explain the idea behind makes it easier to keep track without having to get deep inside the codes.
