Advice for Beginners : Document all the things
August 13, 2018
We’re all guilty
Although the title of this post mentions beginners, many experienced programmers make the mistake of not commenting their code well. Documentation isn’t fun so it’s easy to overlook this important aspect of writing a mature, team friendly code base. I myself have been guilty of this on many occasions & am still trying to improve my documentation skills.
The art of code comments
When adding comments to your code think about the purpose & target audience of each comment. A lot of developers fall into the trap of writing “what” the code does. This is generally a code smell. Unless you’ve written a complicated piece of code that is difficult to understand & you can’t simplify it, there shouldn’t be a need to comment what your code does.
Instead of just focusing on the “what”, also focus on the “why”. Try to answer the question of “Why is your code written the way it is?“.
Here is an example of a bad comment:
// Removes the range of tokens that violated our constraint
const removeRange = fixer.removeRange([ start, end + 1 ]);The example above documents “what” & not the “why”. I would argue that the above comment isn’t very useful. The first thing that comes to my mind when I see that line of code is why is the second argument end + 1? The comment doesn’t offer any help to solve that mystery.
Here is an example of a better comment:
// Remove the range until end + 1 to avoid leaving behind a blank line
const removeRange = fixer.removeRange([ start, end + 1 ]);This code gives us a better insight as to why we decided to write things the way they’re written. Not only this, you should also document any pitfalls that future maintainers of the code need to be aware of. This is especially important if you’ve done something “unconventional” but for a very good reason. You don’t want an unsuspecting team member to clean up things & accidentally introduce bugs in the code.
Example of a situation like this
/**
* Our convention is to require models first.
* However, we must require baseAPI first because it sets up common path lookup
**/
const baseAPI = require('./baseAPI');
const User = require('models/user');Make debugging easier
I have seen projects that have “dreaded” parts that no developer wants to touch. You’ll always find that these areas of the codebase have little to no documentation. Things look a lot more difficult than they actually are when the original author leaves zero clues to help out future maintainers.
I’ve recently worked on a massive code refactor on a project I am involved with. I ended up pretty much going through the entire app & made some big changes. Luckily, the abundance of helpful comments from my teammates made that task a lot easier to tackle (that is what prompted to write about this topic).
I feel like I’ve personally improved my commenting skills significantly in a couple of years since joining this team of developers. This shows the importance of setting a high standard on your project. It will result in developers rising up to the occasion & becoming better at writing helpful comments.
Level up your learning
Sometimes developers resort to copy-pasting code especially when they’re trying to get up to speed with a new technology. Copy pasting itself isn’t a bad thing. However, copy-pasting code that you don’t fully understand is far from ideal. It does make life easy in the short term but makes maintenance of code a big challenge. Also, you might end up inadvertently introducing bugs & performance bottlenecks by using this technique. Make it a rule to always add comments that explain what the code does when you end up in this situation. This will force you to break the habit of blindly copying code. You’ll have to figure out how the code works before pushing it into your project. This will be an uncomfortable transition at first, but trust me this will benefit your code quality & also help you level up your coding skills.
Love them side projects
It’s easier to write good documentation when you’re at work & have expectations to meet. But we often let that guard down when working on side projects. Don’t make that mistake. Give your side projects the same respect as you give your work. Your future you will thank you. I have seen side projects get “put on hold” forever because every time the developer tries to jump back into it, the friction of trying to figure how things work & why certain choices were made is too much. A properly documented side project can be paused/resumed without any issues.
Document all the things
Writing code is just one aspect of a software development. We should document everything that we work on.
- Are you setting up the deployment process? Document it.
- Working on design standards? Document it.
- Making choices about coding conventions to follow? Document it.
This habit will yield many different benefits. Firstly, it ensures consistency in every process that you’re following.
- It’s a lot harder to screw up a deployment if the step-by-step guide is in front of you.
- It’s a lot easier to make consistent user interfaces if you have a design guideline to follow.
- Following coding conventions is easier when you have them written down & readily accessible.
Documentation streamlines all the different aspects of a software developer’s job, not just code. You also end up saving some of your vital cognitive resources when things are properly documented for you.
Documentation gives you wings
If you’re a developer working on an API, I highly recommend using something like JSDoc to generate proper documentation for it. The consumers of the API will thank you. In some cases, documentation could be the “killer feature” that sets you apart from the competition. Don’t believe me?
Well, look at React. React happens to be one of the most popular JavaScript libraries. One thing that makes React stand out from its competitions is their documentation. Their documentation allows new developers to easily look up working examples, get answers to questions & buy into the ecosystem without friction.
React isn’t the only example of a project with great documentation. Stripe is another company that has mastered this & have reaped the reward of investing in making their API easy to consume. When developers are evaluating various tools, documentation & learning resources available end up playing a key role in that decision.
