These practices differentiate the pro from the amateure and a lot of them can also be adapted for various programming languages.
Avoid using comments as much as possible. Comments can sometimes say things that aren’t true, making it harder for people to understand what the code really does. This can cause problems when the code gets changed or updated. Eventually, the comment might not match the code anymore, and then people have to figure out what’s really going on.
A comment signifies that the writer was mentally incapable of providing a well-descriptive class, function, or variable name. It exposes the lackluster attitude of the programmer and forces the team to inherit such an attitude. That way, people can understand the code without needing extra explanations.
example how bad comments are used to explain the code:
# Program to calculate the factorial of a number
def f(n): # Function to calculate factorial
result = 1 # Initialize result variable
for i in range(1, n + 1): # Loop from 1 to n
result *= i # Multiply result by current number
return result # Return factorial
num = 5 # Input number
fact = f(num) # Calculate factorial
print(“Factorial of”, num, “is:”, fact) # Print result
While the code works and the comments provide some clarity, it’s considered better practice to use descriptive names whenever possible to make the code more readable and understandable without relying heavily on comments.
Here’s the same program with clear and descriptive names without the need for comments:
def calculate_factorial(number):
factorial_result = 1
for i in range(1, number + 1):
factorial_result *= i
return factorial_result
input_number = 5
result_factorial = calculate_factorial(input_number)
print(“Factorial of”, input_number, “is:”, result_factorial)
By using descriptive names, the code becomes self-explanatory, eliminating the need for comments to clarify its functionality.
When Is A Comment Bad?
- Noise comments:
# adds to animal list
animal.append(dog)
Description: This comment is unnecessary because it merely repeats what the code itself already clearly states. It adds no useful information and only clutters the code.
- Non-local information:
# Calculate total price (global variable)
total_price = calculate_price(quantity, price)
Description: This comment refers to a global variable total_price, which is not directly related to the calculation happening in this specific line of code. It introduces information that is not relevant to the local context.
- Unobvious comments:
# Increment count (unclear without context)
count += 1
Description: This comment lacks clarity because it doesn’t explain why the count variable is being incremented. Without proper context, it’s unclear what the purpose of this action is.
- Short functions:
def calculate_area(radius):
return math.pi * radius ** 2
Description: This function is short and straightforward, and its purpose is evident from its name calculate_area. It doesn’t require a comment because the function name itself adequately describes its functionality.
Situations Where Comments Are Acceptable:
- Informative comments that clarify the workings of code, especially when well-descriptive names aren’t sufficient.
- TODO comments indicating unfinished tasks or areas for improvement, which should be addressed in the future.
- Comments warning about potential consequences or pitfalls in the code, such as resource-intensive operations.
def perform_database_cleanup():
"""
Perform cleanup operations on the database.
This function deletes old records from the database.
WARNING: This operation is irreversible and may result in data loss.
Returns:
None
"""
# WARNING: Deleting old records from the database
# This operation is resource-intensive and may affect database performance
# Use with caution
# Cleanup logic goes here
pass
- Comments that provide essential information for understanding the code’s purpose or behavior, especially in complex or non-obvious situations.
Top comments (0)