Comments in Programming
Have you gotten into the habit of writing code with comments? After hundreds or even thousands of lines of code, it gets tiring to comment everything you’re doing. However, if you haven’t gotten into the habit, you’d better start and here are some reasons why.
First reason: you’ll forget what you were doing in the middle of your task. Imagine you’re going to work on a new project, but you leave your code for a week to work on something else or to go on vacation. When you come back, you open up your IDE or text editor again to work on the project you took a break from and you see this:
Do you remember what you were working on? You see that you had written a function called “Function” and it was supposed to take in an argument — probably an integer or a float because you called that variable “num.” But, you decided to take your break and you simply put a “pass” into your function so that you could work on it later — and now you have no idea what it was you were going to work on.
This is one of the many examples of why comments are very important in programming. I have definitely made this simple mistake, however, if I had gotten into the habit of writing comments earlier, I probably would’ve saved a lot of time spent trying to read through my code or remembering what I was working on. I will get into that later.
The second very important reason to start using comments is this one: as a programmer, has anybody ever presented you with a problem in their program, maybe a logical error and therefore harder to detect which line the error occurs? If they didn’t have comments, it would be much more difficult to understand their code and what they were trying to do exactly with their program. Imagine that they did have comments though, and how much easier it would be to catch on to what they were trying to do, similar to this:
This program is not too complicated, it creates a Rock, Paper, Scissor text-game. Whether you know Java syntax, you will get a basic idea of the program from simple comments, but more importantly — you will understand your own code.
Writing a program with a lot of code can be an intimidating task, and whether you forgot to write comments or just figured they would cause the task to take longer — eventually in your code, you will wish you’d written some comments.
Now, I will provide a few more examples of things you’d want to avoid if you can help it. One way is by writing comments. When I first began learning to code, I definitely thought writing comments would simply cause my project to take longer and that I would know what I was writing already — it is MY code after all. After two semesters of programming courses at my local community college, I had written tens of pages of “documentation,” meaning UML (Unified Modeling Language) diagrams for my program’s classes, flowcharts designing exactly what my program was meant to do, pseudocode also describing what the code would do, many written test cases that either passed or failed, and of course, hundreds of lines of comments.
I realized that when I didn’t write comments, I would definitely write a program faster, but when I ran it in my compiler, I got tons of errors for things I had no idea how to fix. I’d spent hours trying to figure out how my own code worked and how to fix it. Without comments, the task of writing my program dragged out to much longer than it would had I just decided to write some comments while creating it. I also realized that when I had a question for my teacher about my code, they found it much more difficult to help me when I hadn’t written any comments. Some of them would spend a few minutes simply reading through the lines of code in my program and trying to understand what each line, method, condition or loop was trying to do.
So, in the end, do you believe comments are useful? If you don’t use them, you’d better start. As a programmer, you’d want other people to understand your code, but most importantly, you need to understand your own code. You probably think that only beginners use things like UML diagrams and comments to plan out their code — but that’s definitely not true. Even the greatest of programmers need to use comments and diagrams to understand their own code. Nobody can understand hundreds of lines of code just by looking at it, and that is why there are comments.
