Greater than code

May 21, 2021  |   3 min read

Writing great code is not the only aspect of being an all-round engineer and good teammate, there’s so much more to it -

Documenting code

People say that code itself should be self-explanatory and shouldn’t need additional comments. There’s some merit to this advice but not everything can be self-explanatory. Sometimes it is necessary to add additional code comments or documentation. There can be a whole debate on which piece of code calls for comments and which does not. A simple rule I like to follow is to ask myself if a person with no additional context looks at this code will they understand it or will they need some particular context to understand. If the answer is yes to needing additional context then I write that in code comments or better yet in separate developer documentation.

Keeping technical decision logs

Keep a record of all the technical decisions that were made while working on a project or a feature. You can add excerpts from slack conversations or decisions made during a call or a paring session. The goal is to keep all the necessary information in one place so you or your team member can access that in the future. Don’t rely on your memory to remember everything, offload your knowledge and context frequently!

Writing detailed PR and issue descriptions

We’ve all been guilty of writing lousy descriptions on our PRs or issues. It might just be out of laziness, or we think we don’t have enough time to be bothered with crafting a good description. But writing a good description with all the necessary information is a skill. It will help you being better at synthesizing important information and creating good problem statements. For PR descriptions, writing down all the decisions you took while writing the code will help the reviewers get more context around why you did something the way you did. It can also act as an artefact for your decision log document where you can add a link to the PR that holds all the information.

Writing effective code review

Critique code not people – be kind to the coder, not to the code. This is a piece of advice I received that has stuck with me the most. Always remember that you are reviewing code and not the person who wrote it. Make your reviews oriented towards improving the code and not directed towards an individual. Most importantly, don’t forget to write appreciative comments! if you liked the way they approached a certain problem or wrote some good test cases, whatever it is make sure to let them know. It doesn’t always have to be a criticism.

Taking time to provide feedback

When people ask you for feedback, don’t just shake it off by saying “you did good”. That is not helping anyone. If you want to convey they did a good job, let them know the reason behind it. Or if you think they could do better, let them know what specific things they can do to improve. If you think you don’t have enough context to share feedback then it’s better to let the person know rather than providing some misleading feedback. Feedback is a gift, you should be as thoughtful in providing feedback as you would when buying someone an actual gift!

Sharing your knowledge

We all learn from each other and everyone should strive to share their knowledge back. Knowledge sharing can be done in many different ways. It can be as elaborate as a workshop or as ad hoc as sharing WIP work. Find a medium you are comfortable in and just share. This not only helps other folks on your team gain knowledge but also helps you solidifying your concepts and establishes you as a subject matter expert — a win-win situation!

Creating healthy team culture

Especially in times like these where people are living in a tough reality, it is essential to check on your teammates to see if they are doing ok. A simple act of kindness will go a long way! Having a healthy team culture and cultivating a sense of community is something everyone should strive for. Great work gets done when you have healthy team morale.

No way this is an exhaustive list and I’ll keep on adding to it as I learn them myself.