Comments, Why You Should Reconsider
Comments, Why You Should Reconsider
Our first thought when finishing up a section of code is to fill it with comments. While this was pushed upon us while we were learning how to code in school it is far from optimal. As I am famously told by my coworker, “Writing a comment is an apology for poor code”. For the most part this is completely true; if your code can’t be read by looking at the variable names and given a general gist of how it works by the architecture, then please refactor it. I have and do not wish to spend hours upon hours of time and energy spent trying to decipher what a singular line means because someone decided to name every variable a, aa, aaa, etc.
You may ask yourself, “I understand my code, who cares if anyone else can read it?” My response would simply be, “What if there is a bug? What if you need to come back later and change something because you want a to work like aa?” Remember, you will most likely not be the last programmer on this project, and 80% of the time your code will be in maintenance. Might as well make that maintainable and easy to read.
Take the following code for example (Note: Items in Bold are Comments):
``` #include <iostream> ```
``` #include <string> ```
``` using namespace std; ```
``` string pun(string); ```
``` int main() { ```
``` cout << "What is your name?" << endl; ```
``` string a; ```
``` cin >> a; ```
``` cout << pun(a) << endl; ```
``` } ```
``` string pun(string ui) { ```
``` string aa = "Hello "; ```
``` string A = "!"; ```
``` return aa+ui+A; ```
``` } ```
You look at the above code and go, “Oh, I made this. I know exactly what it does!” It looks bad, but “just to be safe” you go and comment it.
//Standard includes
``` #include <iostream> ```
``` #include <string> ```
//Using namespace standard
``` using namespace std; ```
//Function prototype
``` string pun(string); ```
//Main
``` int main() { ```
``` cout << "What is your name?" << endl; ```
//User input
``` string a; ```
//Accepting user input
``` cin >> a; ```
//Printing user input
``` cout << pun(a) << endl; ```
``` } ```
//Prints user name
``` string pun(string ui) { ```
//First part of response
``` string aa = "Hello "; ```
//Ending of response
``` string A = "!"; ```
``` return aa+ui+A; ```
``` } ```
Maintaining Your Code:
If I am being fair, I liked how the code was before. I would argue all of these comments are irrelevant. But for the sake of arguments, the comments are there. Now let’s say you are NOT the last programmer to work on this and someone else comes in. Who is to say that they will maintain the comments or level of them as you did? This is what could happen down the line:
//Standard includes
``` #include <iostream> ```
``` #include <string> ```
//Using namespace standard
``` using namespace std; ```
//Function prototype
//Main
``` int main() { ```
``` cout << "What is your name?" << endl; ```
//User input
``` string a; ```
//Accepting user input
``` cin >> a; ```
//Printing user input
``` cout << "Hello "+a+"!" << endl; ```
``` } ```
//Prints user name
//First part of response
//Ending of response
Now, look at all those comments. The bottom three no longer apply and there isn’t even a prototype at the top anymore. It has long since been removed. This is the reality of most comments. How do we make our code readable but also not need to include comments? I’ll show you with the code from the first example.
``` #include <iostream> ```
``` #include <string> ```
``` using namespace std; ```
``` string getGreeting(string); ```
``` int main() { ```
``` cout << "What is your name?" << endl; ```
``` string userInput; ```
``` cin >> userInput; ```
``` cout << getGreeting(userInput) << endl; ```
``` } ```
``` string getGreeting(string inputFromUser) { ```
``` string beginningOfGreeting = "Hello "; ```
``` string endOfGreeting = "!"; ```
``` string greeting = beginningOfGreeting+inputFromUser+endOfGreeting; ```
``` return greeting; ```
``` } ```
This code should be crystal clear; it is telling you exactly what it is trying to do. With clear names for functions and variables we can clearly tell what everything does. If we find an issue for some reason, each section of the code is easy to parse through.
Don’t Comment Old Code:
Usually, most programming tips are situational. This one however is not. Never ever under ANY circumstances comment old code. We have repos for a reason. If it turns out that we need the old code then we can just go back to the repo and get it.
You might ask yourself, “Are there appropriate times to use comments?” And the answer is an astounding yes! But we must be sure to not overdo it. If you are writing code for someone else or public use, a public function should have some sort of JavaDoc comment and signature explaining what it does and the arguments it takes in. Other bits of code that give a sort of warning to others are also generally liked, or throw weird exceptions. I have some examples below.
This is a good example of a warning comment:
/*
* Please do not run or modify this function, it takes 3 hours to run
* and is vital to the testing suite, if you need to modify this function
* please come and contact the team lead.
*/
void testResyncingInputDataFromUserToDatabase() {
...
``` } ```
The comment above clearly tells you why the function should NOT be run or modified because just looking at the function, it seems like a simple test function. But the comment warns us this will take three hours of our valuable time.
My other example is one for a public function:
/**
* This function calculates the total damage the player takes after all resistances have been accounted for
* @param incomingDamage the amount of incoming damage
* @param resistances the amount of each resistance type the player has
* @return the amount of damage done by the attack
* @since 1.0
*/
``` void calculateTotalDamageAfterResistances(int incomingDamage, array resistances) { ```
...
``` } ```
What Should You Do?:
Remember, even though you shouldn’t use comments all the time, there are still a lot of valid reasons to use them. Like most things in programming, it is all down to what is best for your current situation. Sometimes you have rules put in by the higher ups saying you must comment your code. In that case it isn’t so much as writing a comment as it is writing a good one. Either way, now you have the knowledge to make your code better.
