If you have to create documentation for your code, one of the best ways you can save yourself time and effort is by writing self-documenting documentation. But What is self-documenting code and what are its advantages? This article will explain what self-documenting documentations are and how to write them.

What is self-documenting code and what are its advantages?

Self-documenting documentation is a way of documenting code that allows others to read and understand it without any additional information. Since the purpose of self-documenting documentation is to save time, and not to explain how something works, the reader does not need to know any additional information about the code besides what it does and how it does it.

The two most important things in writing self-documenting documentation are:

a) To use meaningful names and labels for variables, methods, etc.
b) To use meaningful code comments (when needed).

a) Using Meaningful Names and Labels

When programming in any language, you have to give your variables, methods, classes and other pieces of code names that have meaning. The names and labels need to be meaningful so that the programmer can quickly identify what they are supposed to be used for. Examples of meaningful names and labels in programming language include:

• Variables Names
• Method Names
• Class Names

b) Using Meaningful Code Comments (When Needed)

Since code comments can contain a lot of useful and important information, most programmers like to use them to describe what each part of the program does and how it works. This is how you write meaningful comments:

When doing self-documenting documentation, the important thing is not to reinvent the wheel and try to explain every line of code. Instead, focus on explaining the high-level idea of each piece of code and leave it to the reader to understand how it works. As a result, you will most likely end up with self-documenting documentation that has all of the aspects of good programming documentation but is also meaningful and easy to read. Good examples of self-documenting documentation are:

When writing self-documenting documentation, you should use as many comments as possible while still keeping your document easy to read and understand.

Some things to keep in mind when writing self-documenting documentation are:
1) Whenever possible, use detailed code comments that explain what the code does so that readers know clearly what is going on, especially if the method does a complex function.
2) Use meaningful names and labels for variables, methods, etc.
3) Other stuff related to self-documenting the documentation

A good example of self documenting code is the following:

def calculatePaymentOwedByUser(listOfUserAmounts, userId, amount):
usersPaymentsList = {}

def calculatePaymentOwedByUser(listOfUserAmounts, userId, amount):
  #Calculates the amounts owed for each user and returns a list of the owed amounts  
  usersPaymentsList = {}
  for userAmount in listOfUserAmounts: 
      amountOwed = 300 * userAmount
       usersPaymentsList.append(amountOwed)
return usersPaymentsList

Notice how the variable “usersPaymentsList” is used as a meaningful name for the variable and its role in the program is clear. Notice also how each part of the program is commented on so that readers are able to understand what each part does. As you can see, while this piece of code may not be hard to understand or write on its own, it is much easier to understand when you have comments that describe what it does.

Advantages of Self Documenting code

1) It is easier to read and maintain.
2) It is easier to troubleshoot.
3) It can be easily changed or extended by other programmers.
4) It should prevent bugs from being introduced into the code because the requirements are clearly stated in the documentation.
5) It saves a lot of time for you when you come back to update or extend your code because all you have to do is add comments to help explain how each piece of code works. This means that you do not have to rewrite or delete any part of the code, which would take a lot more time than just adding comments.

Conclusion

In the case of large scale software development, if you want very high quality and maintaining software code, Self Documenting documentation is a key to success. It doesn’t mean that one should document all the lines of code but it means the developer has to put some effort into meaningful names & labels and comments.

You might be interested in why do we need QA testing.