Introduction
In computer programming, comments are a programming language construct that provides a mechanism for embedding information in the source code that is (generally) ignored by compilers, because their believe that the code should be written in a way that makes it self explanatory. Other people believe that source code should be extensively commented since it makes possible to follow the written code more easily.
How to Write Comments
Should I write comments? What is good comment? Is it possible to write comment for a class in 5 minutes? I would discuss these questions. I would be happy if, after reading, you will be thinking that good comments are an important thing to your project success.
I must admit that I hated to write comments. I was finding them boring and unnecessary. And the worse thing is that I was afraid that during my design some of my methods or classes might go away together with my time spent for writing my good comments. So the first thing I would discuss is.
Why?
Here is the first reason for comments. Comments can make your design clearer. You could mark the class with its responsibilities using comments. You can check then how much your class respects its responsibilities, and that it don’t do something which is not its responsibility. Moreover, you can check how much your class respects Single Responsibility Principle and make some decisions to improve the design.
But I think that primary reason which can force you to write comments is to make your code understandable for others. The rule is simple. If you will hide your code for forever - nobody is going to know if it is commented or not. As soon as you are going to share your code with some other person - unless you are not writing it all together from the beginning - he or she will be happy to see your class comments.
Of course you could be happy to explain it to everyone personally. But you want to avoid phone calls asking what your class does while you are on vacation.
How?
What is good comment? Should we judge how good the comment is by its word count? Should we have each method commented? I would say we don’t, or else our comments could end up time-consuming for us and being boring for our readers.
Comments can summarise code or explain the programmer's intent. This is called the why rather than how approach. The two are often close, but not always. According to this school of thought, restating the code in plain English may be a waste of time; the need to explain the code may be a sign that it is too complex and should be rewritten.
"Good comments don't repeat the code or explain it. They clarify its intent. Comments should explain, at a higher level of abstraction than the code, what you're trying to do."
Comments should also be used to guide a new programmer through source code that performs some task. In this case almost every line should be commented. New programmers can gain much insight in various branches of programming and computer science by reading through extensively commented source code. Typical things that could be commented on are function calls and arguments, algorithms used, and caveats.
Sometimes a programmer thinks up a neat trick to perform a certain task. Comments could in this case provide an explanation of the trick used. Although the why rather than how approach discourages such comments, sometimes an explanation is just what is needed to make a future programmer understand what a certain piece of source code is doing. This might especially be true in the case of rarely-used optimizations, constructs or function-calls. For example, a programmer may add a comment to explain why an insertion sort was chosen instead of a quicksort, as the former is, in theory, slower than the latter. This could be written as follows:
list = [f (B), f (B), f ©, f (d), f (a), ...]; ; Need a stable sort. Besides, the performance really does not matter. insertion_sort (list);oÝ÷ Ù+rë¢iÛ-ÊW¬j·¨~קj ÞyÛ©¢vÞ~Þjèç-²Ö«¶Å,¹©eÊ趦ê즷z»-ÊW¬¶j·jÌ¢j ü×b}øº[m¡ºÞjAhìZ^ Ërç(g§¶Ç(ºWe¢%G+ºÚ"µÍÊÈÈ HÛÛ[Y[Ù KoÝ÷ Úæk&Þ) ¶¬jëh×6/***************************\ * * * This is the comment body. * * * \***************************/
If a programmer's editor doesn't manage the second variant automatically, it may discourage changes to the comments, thus leading to comments which are out of date with respect to the code. On the other hand, the visibility of the second comment variant is much higher
When?
I dislike writing comments which will be thrown away. During my design, I create new classes, play with them, throw them away and create new instead. I would find a way to save my time and write a comment when I have a decent hope my class will remain within the system.
The point to start writing comments is... when the code is ready to be presented for others. This could be the time before commit to a main source repository, or insert your case here. For this time, I have pretty stable class design, and good chance my comments will live long. I am pretty sure with my class’s responsibilities and what classes it will collaborate with. I can spend as much as 2 minutes writing this information as a class comment. Everybody’s happy!
Coders sharing their experience:
People who had their experience with the comments have posted their experience.
10048 said...
Interesting post. Somehow some developers don't get it. I am old school and the question of commenting your code has been around a long time. As a manager of developers on many large and small projects I would not tolerate undocumented code. The developer is not writing code for himself (assuming he is in the employ of a company,) he is getting paid to do a job. If the developer can not spend time to document his code (instinctively) then I would not expect him to last very long on a project.
Could you imagine in todays "open source" culture that an application's code not be documented? This would set our industry back 30 years.
dkrukovsky said...
Open source project will definitely have a good advantage if its code will be well understandable. In this article, I tried to show several problems which stops from writing comments, and how to deal with them.
Richard C Haven said...
Beginning coders comment nothing;
Novice coders comment the obvious;
Experienced coders comment the reason for the code;
Master coders comment the reason for the code not used
JimS said...
Good thoughts on comments. As an embedded developer attempting at times to use open source stuff I would plead with the community to please comment your routines. In the embedded world a lot of times we don't have a POSIX environment or sometimes even an OS. Trying to adapt open source stuff becomes a challenge because we cannot just configure make... We have to re-write the code to adapt it to our environment. The greatist help here is comments on each of the routines (methods) so we can see the gazinta's and gosouta's what they do and what the routine does. I've given up on a number of interesting open source tools or libraries because they don't do this and I don't have the time to decode cryptic routine parameters and try to guess what the routine does and what the output might be.
Anyway, document your stuff and your project might just end up in every parking meter on the planet...
Oscaruzzo said...
You say But I think that primary reason which can force you to write comments is to make your code understandable for others.
Broofa said...
I would disagree that the primary reason for commenting is to make your code understandable to others . Yes, it is a nice (and necessary) byproduct, but the primary reason Is that the act of documenting will improve the quality of the code you write. This sounds strange, but it's much harder to document poorly written/designed code. Thus, you become much more aware of the inconsistencies and design flaws, and tend to avoid them.
More from me on this subject here
The Absurd Theist said...
"But I think that primary reason which can force you to write comments is to make your code understandable for others"...I agree with Oscaruzzo...I AM the Other...6 months from now I may have to revisit my own code. No ones mind is perfect and cannot remember everything it ever wrote. Comments are SELF-reminders.
Anonymous said...
Interesting read, but a few comments.
Disclaimer: I am a teacher in embedded systems/robotics/computer architecture/...
When I teach programming, an integral part is spend on how to comment code. It is not only important, as you said, to explain code to others. It is also important to keep remembering what you actually did with the code you wrote several months after you wrote it and after you have moved on to a different project.
Secondly writing your comments before you write code (as some other poster here mentioned) can lead to a clearer/more structured implementation of your routine/method/class whatever. It can help you to think about how to write the code the best way possible (i.e. design code, not 'hack it together'*). A clear overview of the arguments a function will take and what it returns can lead to a cleaner implementation of the code to do the actual work.
If not, write comments as soon as some part is 'finnished', whatever that means.
And by the way, keeping your comments up to date should be a part of the code maintenance process.
In the embedded world especially (as again someone mentioned here) it is very good practise, and luckily very common, to see very good code commenting. To see an excellent example, get your hands on the uC/OS-II source written by Jean J. Labrosse.
Lastly, it is my opinion that well documented/commented code looks better than non-commented code.
sprezzatura said...
A programmer doesn't truly learn the importance of comments until he has enough experience under his belt to have been in the horrible situation of staring at code he wrote years ago... and not understanding a thing!
Mario said...
Last thing I had to do in my last project was to complete and translate to Spanish all comments/javadoc. I even had to document other's code. During that process I discovered that some comments were a little difficult to write, like the ideas didn't fit quite naturally. Then I realized that the code wasn't as good and simple as it should be.
If I refactored the code in a way that the comments and docs were simpler that would mean that the code would represents the ideas behind it in a more elegant manner. And I think it will represent better code.
If you cannot easily explain what you are doing...something is wrong (either with your doings or you)
. Totally agree with neil cherry: Assembler without comments it is worthless ( or a good trick to keep your job).
Anonymous said...
"Don't comment your code if you wanna keep your job"....in seven years of professional coding, I've seen a lot of people attempt this strategy, and every one of them eventually got fired.
At some point, management decides that the pain you will continue to inflict in the future exceeds the pain of transition. Also, bear in mind that at some point, your application starts to become obsolete, and nobody will want to give any new projects to you.
Meanwhile, people who write clean, well-commented code keep their jobs because they make everybody happy.
btw, a wonderful example of well-commented code is the source of SQLite.
Chie`s personal comment:
I always comment my code, unless I do that its becomes weary hard to find the right code snippet I need ( & it takes long to find it. ). I have many code samples not only in autolt, but also even more in other languages, like php & c++. Its hundreds & I can imagine that programmers have them even more.(Why to write the code again if u can simply copy paste already once written one. The comments & bookmarks are vital hire!!)
It is also important for me to work with commented code since it makes to follow it more easily not only for myself but also for others, if I decide to share it.
More comments can be found hire:
http://dkrukovsky.blogspot.com/2005/07/how...337768496950173
Used material:
Personal Experience &:
Comment - Wikipedia, the free encyclopedia
How to Write Comments by Denis Krukovsky
Thinking outside the box
