When I began my first internship after graduating from engineering school, everyone kept saying how important documentation was for coding. I couldn't help but wonder, 'Why? I already understand what I'm doing,' 'Is it a waste of time?' or 'I could write more code instead of documenting.' Maybe not everyone feels this way, especially experienced developers who've struggled for days or even weeks trying to understand code from others who didn't include any documentation realizing more and more the importance of documentation.
Documentation?
Documentation may have different definitions if you look at different fields even in IT. Design documentation, Project Management Documentation, Programming Documentation, etc. Each holds a different section of importance in a project. For example for code, It’s definition is, “It is a collection of documents and code comments explaining how code works and how to use it.” There may be standard in place that helps to make documentation consistent in any field but at the end of the day, all it does is help the user and understand following things:-
- What is to happen?
- What did happen?
- How did it happen? and Conclusion for others to use.
Why Documentation?
Since I am working in the programming sector, I’ll be explaining why we need it in coding using the above points.
What is to happen?
The first point, ”What is to happen?” helps us understand the idea of what we actually need to do so that we can create logic to face that problem more easily. You may say I can visualize the code all on my own so there is no need to write it down that’s where I say, It’s okay if the logic you are developing is very simple but what if it’s not? What if the logic you are developing is very complicated and you get lost on the logic you were developing due to bugs? That’s where documentation on what is to happen is required. Even if you are developing a database, the database you just end up with might not be the best result. There are lots of benefits of doing documentation on coding what you are about to do.
/**
* To check if "n" is a prime number
*
* What I know?
* 1) Prime number is the one which is no divisible by no other number but itself and 1
* 2) I don't need to include 1 (Divides all numbers)
* 3) I don't need to include n (Divides itself)
*
* Range should be from 2-n
*/
What did happen?
When building logic, there might be an occurrence where you find a great idea that you didn’t find anywhere on the internet and you implement it. Since no one but you implemented it, others might have no idea how it works. And the thing about coding is no matter how clean code you write, It does get a lot more difficult to remember what you did to solve that problem later.
Several developers may have problems in this section. In my case, I was trying to create a three-lane game, and I found a great way of making it work without using an addition. But when I was trying to put the finishing touches on it, I had no idea how everything was working. It took me another hour or so to go through everything to finally get what I actually did.
So writing about what happened in coding helps you revisit the code and understand the genius idea you had not only for yourself but for other developers as well.
function primeNumber(n) {
let isPrime = true;
if (n % 2 === 0 && n !== 2) {
// All even numbers are not prime except 2
return false;
}
for (let i = 2; i < n / 2; i++) {
// We have dont n/2 since any number which is greater than n/2 while dividing will give result less than 1
const reminder = n % i;
if (!reminder) {
isPrime = false;
break; // Since we don't need to check for other numbers if it's not prime
}
}
return isPrime;
}
How did it happen? and Conclusion for others to use.
This is the point which most of the developers are most familiar with. Writing about a function or a class including what it does, what is returns, and what are the requirements for it to run. If someone is using JS, there is JSDocs and another programming language has a similar documentation standard which is used by almost all developers for the reusability of the code.
While the other two parts are used for the purpose of understanding the code, this part is only written for the functional aspect. For example, you want to find a prime number and someone has created a function already to calculate the prime number, you don't usually need to know how they are calculating the prime number, you just want to know what they give as result and what they take in input.
/**
* The function checks if a given number is prime
*
* @param {number} n - The parameter "n" represents the number that we want to check if it is a prime number or
* not.
* @returns The function is not returning anything.
*/
How to document a code?
To document a code, the simplest way is to use the standard commenting such as JSDocs for JS. It's most widely used and even if a new developer opens the code they can understand it quite easily.
The smallest way to document a code would be to use proper names for variables and functions which makes life way easier for refactor purposes or to change later down the line.
Not Always Possible
Saying how documentation is required, we might be pushed to think that we need to include it everywhere, but as we developers know, it's always not the case. Tight deadlines, and managing multiple projects, are only a few of the problems one might face while on a project which might not make it possible for us to write documentation at every moment.
Writing code in a particular architecture such as Clean architecture, or atomic structure pattern can also be a way for other developer to understand the code more easily.
Conclusion
Documentation even if we don't use at all is there for easement of ourselves and/or other developers working together in the project. Adding the small line of comment indicating what happens when you run a function helps a long time for any other developer trying to work on that project and if you work on it after months then it will surely be ease for you as well.
Top comments (15)
I also heard how important documentation is, but after working professionally, I realized not many codebases are extensively documented because most companies prioritize speed. Teams seem to prefer to utilize types and comprehensive tests rather than spending time on writing long documentation which is hard to maintain as the codebase changes.
Yes indeed! Documentation is not always possible and even in a few cases not feasible as well. But in case of collaboration, if we have to onboard a new member or we have to work on the same feature, the documentation does increase the speed of the development. There are always trade-offs in selecting things we do in a project.
Agreed, even a little documentation is always better than no documentation
Within my teams, we've been a big fan of Architecture Decision Records (ADRs).
There is also good tooling for their creation / maintenance.
For us it severed two important purposes:
Maybe doesn't work for all teams, but I would encourage researching it.
Documentation is the failure to use good explanatory names. IMHO
Yes indeed. Good names do play a role in us understanding the code better. Requirement of documentation might not be required in every case as well. But when there is complex logic in the system, I believe that having documentation is more beneficial.
I only partly agree to this.
For me the crucial part of documentation is why it has been implemented in the way it was; if not obvious. That typically cannot be realized with proper names.
you implement the documentation and then you never update it
Code never lies. documentation always lie
There are other type of documentation that might not be related to coding directly but rather important, you might have:
As of coding documentation, you might have an HTTP API documentation, a doc. about a collection of events in a microsevices architecture or a collection of custom events in a micro front-end architecture.
Yes, indeed there is other documentation not relating to coding directly for a project which has an even bigger role. Even in coding itself, there might have been more points that I might have missed. Thank you for sharing the points.
Thank you so much 😁
Did i miss something? The function in your example returns a boolean which indicates if the given number is prime or not.
Instead of commenting the obvious, you forgot the important ones. E.g. preconditions like that n must be positive.
Your function will return true for any negative number which is not dividable by 2.
Is the flaw in your
primeNumberfunction intentional?Actually no, Thank you for pointing it out. I had noticed it before but forgot to fix it.
In my country is not exist internship, stay employed or unemployed.