To comment code or not to comment code

A colleague messaged me asking what the context was behind a certain code function and why it has some strange logic. Obviously, i didnt want to invent work for myself so i said “not sure, working on something else”, to which they responded “asking because you are the author on the commit.”
In the words of another cartoon, that hitted me hard.

I had no little memory of writing this obscure and apparently esoteric function. Did some searching and was able to track down some notes i had on conversations from years ago. There was an easy way I could have avoided this: code comments.

For today we are focusing on code comments. Code comments might be the next holy war between software engineers. Some engineers have radical views with on team #nocomments, and engineers that over-comment code, resulting in blocks like below:

A no value add code comment, that just wastes everyone’s time

NOTE: BowTied_Raptor from Data Science & Machine Learning 101 is posting parts of this article on his SubStack in collaboration with BowTiedCrocodile from The Bit Shift. (I still google bitwise operations every time with no exception). Couple perspectives covered in the aggregated post, and I myself am excited to read this no-frills perspective on code comments. This version of the post is like my “Directors Cut”, and feature my unedited and uncut opinions on the matter.

Code comments are lines in a code file that are not executed, with the purpose of providing context or an explanation about the code. The symbol for comments vary by language, but in python it happens to be a # sign. Many languages also support multi-line comments which create a block where comments can be entered, in python this is the triple quotes “““ Comment “““ . Its customary to begin code files with a multi-line comment block explaining various things about the file.

Comments can be seen as a to note unintuitive code or provide context to why something is implemented a certain way. The difficult part is being the judge on where the line is for that. Hopefully as you work in a team you’ll figure out the preferences of your colleagues and engineering leadership.

This should be review for anyone technical.

There are four primary reasons for commenting code. The first being readability, which has five sub-areas where comments can be helpful:

1. Clarifying purpose - This often involves explaining business logic. For example, I once created an automation script that restarts a process. Before it returns success, it checks a couple of network connections to ensure they're functioning. I included a comment explaining that this check is necessary because the software must maintain a connection to the main server. Someone unfamiliar with these systems might not know this, making this comment valuable.