Code Documentation: Necessity or a Waste of Time?

Code Documentation: Necessity or a Waste of Time?

web developmentprogrammingdiscussionbeginner

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:-

  1. What is to happen?
  2. What did happen?
  3. 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.