How do comment your "code"?
-
So, i'm not the guy that likes commenting it's own code. (I feel pretty disorganized). Now i think about commenting my stuff. (I've got an useful method!)
So the question is, how do comment your code? Do you comment everything?
-
I comment all non-vanilla code, because it doesn't matter if you are reading foreign code or your own code from months or years ago - you don't know why you've used a specific piece of code or pattern and commentary will definitely help you.
-
I actually first write my logic with comments, a.k.a. pseudo-code it, then do the implementation below the comments - and there you have it, fully documented, and at least for me, the workflow is faster and easier.
Perhaps it is worthy to mention that there is a difference between commenting code and documenting code with comments.
-
Comment everything that isn't obvious from simply looking at the code. If it took you a while to figure something out, your future self (and other programmers) will thank you for explaining your logic. I have also found that, sometimes, reviewing my logic in this way exposes errors in my reasoning.
-
I just a quick statistic about my code - comments are about 10% of all LOC, for more complex logic and algorithms I find myself commenting every logical unit block of code, sometimes even every line.
Comments in code never hurt anyone, and the parser is quick to skip them, so there is no reason not to comment as much as you want. The stuff I don't comment is that which is completely obvious, it is an excellent way to what is going on and where, which is extremely useful in production grade code and even more so if it is something you worked a long time and forgotten or something done by someone else.
Plus you can always remove the excess of comments if you plan to share the code and you are afraid too much comments may make you look noobish :)
In short - comment as much as possible without getting excessive, and if other people are supposed to use your code - document everything directly into the code for use by a documentation system like doxygen.
-
I just found this article, has some insights about comment the code.
"http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-source-code":http://kotaku.com/5975610/the-exceptional-beauty-of-doom-3s-source-code