1
General testingHow ToQaSoftware

What Is Self-documenting Code And What Are Its Advantages

3 Mins read

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.

Don’t miss amazing tips!

1
Related posts
How ToProgrammingSoftware

How to link flutter with firebase email password authentication

11 Mins read
Table of contents0.1 firebase email password authentication output flow0.2 Creating our email password authentication on flutter0.3 Step 10.4 Setting up firebase and…
How To

How To Implement Data Tables In Cucumber Using Selenium Ruby

17 Mins read
Table of contents0.1 Advantages of Behavior Driven Development0.2 What is Cucumber?0.3 What are data tables in Cucumber?0.4 How to implement data tables…
Automation testingQaRuby

Selenium Ruby Example And Deployment To The Cloud Grid

13 Mins read
Table of contents0.1 What is Selenium?0.2 How does Selenium WebDriver in Ruby work?0.3 How to use Selenium with Ruby?0.4 How to run…

Leave a Reply

Your email address will not be published. Required fields are marked *

− 2 = 4

×
General testingQa

Why Do We Need QA Testing