Self-documenting code is one of the biggest myth in the software development industry. It is common for someone to think that their code is pretty much self-explanatory, either because it is so simple or they are the author so they should have known it better than anybody else. However, not all of us can realize the fact that while the code is pretty transparent for ourselves, other would not have the aspect as we do despite how much experienced they are in the field. In this blog post, I would like to reason that code comments have a lot of value and documentation has more value than just explaining how functions / software works.
From that all of us can understand, code documentation is basically a collection of descriptions to explain what the codebase does and how it can be used. It can be a simple explanatory comment that locates above a function or a block of code, or a full fledged developer handbook, usually complete with prescriptive style dos and don’ts overviews of each part of the application, and approaches to the most common types of coding task. Like a lot of people would think, the general reasons why we think our code is “self-documenting” mainly because our applications can be boiled down into functions or objects that have one specific task and that task should be represented by the name of the functions or the objects and for me, this is not true at all, especially with large project with lengthy codes and potentially has functions that is named a little bit similar and have some common traits with each other. What we mostly don’t really think about is that code without comments is basically force the reader to go through the how it is implemented to figure out the why. With that being said, we can see that documentation are important to transfer the knowledge of what that function really do so that people can reuse it by just not knowing how it was implemented and that is fine. Not just giving user the instruction, code comments are also used to provide example usage of the code, provide the trade offs or pros and cons of the current implementation, marking the possible improvements in the code, possibly how to use it effectively with others APIs, and it serves as the most effective communication between authors and readers.
Another flaw of self-documenting code mindset that we usually think is that because we are standing in the developer-only point of view. To be clearer, what I meant is that we only seeing the value of documentation as allowing people to understand how the code works and documentation should be for every possible user. Developers only think about developers when it comes to software. It is true that a vast majority of the software users are end users and by having a good documentation can make the software more approachable by users that are not developers.
Article reference can be found here.
From the blog #Khoa'sCSBlog by and used with permission of the author. All other rights reserved by the author.