What is a good comment/code ratio?

A comment is a piece of code that isn’t executed by the compiler or interpreter when the program is executed. Comments can only be read when we have access to the source code. To answer the question about a  good comment/code ratio, we need to first understand the needs that require us to include comments in our source code. 

Why are comments needed?

It is very well known that comments don’t improve the quality of the program. They improve the readability and understanding of  the source code.Following are some of the specific reasons for using comments in our source codes.

1. We use comments to specify the license or copyright of the source code.

When we write any source code for a commercial purpose, it is customary to specify the name of the author, date and time at which the source code was created. We also specify if the source code is copyrighted or licensed and whether the source code can be used and modified without the permission of authors of the code.

2. We use comments to specify contracts if any.

If the source code is written for a different firm for commercial purposes, generally the conditions for usage, copyrights are specified in the source code. When anyone tries to modify the code, they may know in advance if they are allowed to use or modify the source code so that no legal trouble comes in future.

The above two uses are accomplished by using header comments in the source code. Header comments are written at the start of the program file and they specify the author, date of creation, licenses and describe what the source code in the file does.If any modification is done in the source code by anyone, it should also be listen in the header comment so that others can get information about it.

For example, following code snippet shows a python comment in the starting of a python program file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Created on Sat Mar  6 14:13:03 2021

@author: aditya1117
This code is for pythonforbeginners.com
"""

3. We use comments for documentation of the source code.

When any new framework or library is written for any programming language, it includes specification of each of the methods used in the source code and their use cases. It is done to make the users of the framework aware about how to use the functions and methods in the source code. It also specifies about the parameters, desired input values and expected output of the functions and methods so that programmers can use the code with very little difficulties.

For documentation of source code, we use comments above every function. These comments are also called function header comments.For example, the comment in the following example describes the function defined after it.

#This function is an example of nested function which defines another function and executes it when called. 
def outer_function():
    x=10
    print("It is outer function which encloses a nested function")
    def nested_function():
        print("I am in nested function and I can access x from my enclosing function's scope. Printing x")
        print(x)
    nested_function()

4. We use comments to clarify why a specific statement is written in the source code.

When the usage of a particular function or expression doesn’t seem obvious in the source code, we use comments to specify why the function or the statement has been written there. It increases the readability and understanding of the code.

5. We use comments to specify the instructions which helps in debugging the code.

There may be a need in future to modify any part of code if any error occurs. In this case the programmer who will perform correction of source code will need to know about the properties of the functions. They will need a clear understanding of each statement included in the code so that they can improvise it. For the programmer to understand the code at such instances, comments should be added to the source code whenever it seems necessary.

The above two use cases are accomplished with the help of inline comments. 

What should comments in the source code do?

1. Explain why a statement has been written.

A comment needs to be able to explain why a statement has been used in the source code. Again, the comment should explain why the statement has been written only when it doesn’t seem obvious to the reader. Redundant comments should not be added. Instead of increasing the understandability of the code, comments may decrease the readability of the code if they are used without proper need.

For example, The comment in the following code is explaining that a python dictionary is being created which anyone can identify from the code. Hence the comment is redundant.

#define a dictionary
myDict= {"Name":"PythonForBeginners", "code":"PFB"}

2. Should not explain how the statement performs any operation.

If someone has been writing codes for a significant amount of time and is an experienced programmer, they can easily understand how the statements written in the source code are executing. They will not be able to understand the code only if they cannot figure out why the statement is used. So, the comments should not try to explain how any statement works.

3.Specify the metadata about the program file.

The comment at file header should specify the author, date of creation, licenses and describe what the source code in the file does. If any modification is done in the source code by anyone, it should also be specified by the header comment so that others can get information about it. The comments at function headers should specify the signature, input details, functionality and output of a function.

Conclusion

Having read the details, now we can address our initial question about comment/code ratio. It should be understood that there is no standard code/comment ratio. We can use any number of comments as long as it serves the purpose. But it should be kept in mind that we should not include redundant comments in the code and we should not comment about obvious things written in the source code. Comments should be used for enhancing understandability and maintainability of the source code and should not explain every statement in the code.