Your Good and Bad Friend: Comments in Programming

Soner Yıldırım
5 min readMay 20, 2023

How to and not to comment.

Photo by Joanna Kosinska on Unsplash

Comments are natural language text embedded in code that are meant for human understanding, not for computer execution. Here is a simple example:

# Calculate BMI: weight (kg) / [height (m)]²
bmi = weight_in_kg / (height_in_meters ** 2)

Comments in programming are used for a variety of purposes such as a “note to self” to document specific implementation choices or to highlight areas that need review in the future. Comments are also important in collaborative settings where many developers work on the same project. They help developers understand the purpose of a piece of code, serving as a way of communication among developers. They can also help clarify the functionality of specific parts of the code or explain the purpose of a given function or routine.

Although comments can be highly useful and necessary in some cases, they can sometimes do more harm than good if not used properly. In this article, we will talk about how to make the best out of comments in programming as well as how not to use them.

Bad comments

There are a few reasons why a comment can be considered bad. For instance, explaining what a function does through a comment when the function’s name should convey the same information is…