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.

• Comment out a block of code in Python
• How to write comments in Python
• How to create Multiline Comments in Python

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.

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