There seem to be two schools of thought when it comes to documentation within codebases: you either believe code should be documented or you abhorrently hate documentation and refuse to ever write a docstring.
Nowadays, many professors require their students to write documentation for every function — deducting points if a student forgets to accompany their code with documentation.
On the other hand, many people argue against in-line documentation because it gets out-of-date quickly and people believe code should be self-documenting.
According to Wikipedia, self-documenting code “follows naming conventions that enable use of the system without prior specific knowledge”. It’s a given that any good programmer should meaningfully name their variables so that they describe the actual functionality of said variable.
However, how much prior knowledge should you expect other members of your team to have? Is it expected that the person whose reading your code should be fluent in the language you’re coding in? And how do you balance readability and conciseness?
Balancing readability and conciseness
Here are 3 different ways a return statement within a function could be written in JavaScript:
1. ... if (fruit != null) { return fruit; } else { return “apple”; } 2. ... return fruit != null ? fruit : "apple"; 3. ... return fruit ?? “apple”;
The first statement is technically the most readable — especially to a junior developer who is learning JavaScript for the first time. But, you can see how silly it is to argue that the first snippet is the best way to check if the variable fruitis null and return "apple" if it is. Whether a snippet of code is considered readable/self-documenting is so subjective and there is no right answer.
Additionally, as code gets more complex, the barrier to entry gets much higher for someone with no prior knowledge of the codebase to understand what’s going on from the first glance. The matter of fact is that a programmer can be extremely thoughtful, use best practices, and intentionally name their variables and it still wouldn’t be considered “self-documenting” for many people.
For example, you could have a function that implements the knn algorithm blatantly named knn and someone who has never heard of the algorithm before will still have no idea what the function is doing.
When writing code there are many factors to be taken into consideration including readability, conciseness, modularity, and the list goes on. And you should do all the best practices involved to produce self-documenting code, but it would be quite difficult to definitively label a codebase as “self-documenting” purely because of the subjective nature of the term.
But how does documentation play into the picture?
VS Code Docstring Skeleton Generator and AI Doc Writer Extension
One of the main arguments against documentation is that it gets out-of-date quickly. If someone changes the code and doesn’t think to change the docstring, the compiler will still compile with incorrect documentation. Many people also argue that documentation should only explain the why and not the what.
However, the argument for documentation is that no matter what prior knowledge you have, it decreases the barrier of entry for quickly and easily understanding the code. If all of your functions are documented, then it is objectively easier to read the plain english description of all the functions rather than reading the code and trying to make sense of the logic amidst the syntax.
Additionally, almost all programming languages have a defined format for function, class, and variable documentation. For example, when I was learning Java, I would constantly reference the Oracle Javadoc that showcased documentation for Java standard’s String and Array classes.
In this case, the documentation is useful because if it didn’t exist I wouldn’t know which functions existed in the first place. Along with a documentation style, programming languages usually have a software that gathers all the documents and generates a page that can be easily searched through. This is helpful if you’re providing an API as a service and your customer wants to know how to work with your software. In these cases, the documentation is helpful because without it others wouldn’t know about the existence of certain functions and it ultimately promotes discoverability.
In addition to software that compiles your documentation into a page, there are tools that aid in documenting code. For example, VS Code has a feature that automatically fills in the parameters and creates the structure for the standard documentation format.
To take it one step further, the AI Doc Writer for Python, JavaScript, TypeScript, C, C++, PHP, Java, and C# extension fully writes out the entire docstring including the function and parameter descriptions.
With new tools like the VS Code Docstring Skeleton Generator and AI Doc Writer Extension, the activation energy required to document your code is now much lower — instead of spending 30 seconds to document your code you can spend 5 seconds generating documentation.
The discussion about code documentation is a multi-faceted one. There are many factors that play into code quality that go beyond documentation. With new technologies arising to make it easier to document code, the argument that it’s difficult to keep documentation up-to-date diminishes.
Ultimately, I do not have an answer for whether self-documenting code truly exists or not, but rather I advocate that all programmers should code with best practices in mind and with the intent to make it easy for others to understand it.
Full Article: Hahnbee Lee @ Better Programming