When it comes to programming, writing comments could often be as important as writing code itself. Even though the comments left in the program will be ignored upon execution, it is important to realize that the software is written to be run by computers, but understood by people. Even the most amazing code needs to be maintained or updated, and that’s when someone would need to figure out what is going on in the program. Adam McKerlie points out that commenting one’s code comes close to an art form.
No matter what other people say, commenting source code is an art form. It takes finesse (and sometimes an English degree ) to properly comment your code.
The two main camps seem to be too much commenting vs. not enough. Some students understand their own code, so write very little to no comments. Others fall to the opposite extreme and comment everything they write.
// z is the sum of x and y z = x + y;
I think that both sides are completely missing the point. This might or might not be the teacher’s fault in explaining the concept behind the use of comments in code. The single most important point I would like to establish here is: comment to explain why you’re doing something, not what.
The what part could often be easily understood from the code itself. Some programming languages, such as Ruby, are very clean and easy to read. Well structured code could often be described as self-documenting. Some might use this as an excuse to not write any comments at all – it’s easy to see what
z = x + y; line does. Though returning to that example above, we still don’t know why it is so.
The benefits of well written comments come from better understanding of the program. Comments help teachers evaluate your code. Comments help peers to help you out with your code. Writing out the why part will often help you figure out how to better approach the what.
So tell me, why are you writing this method / function / line of code?