How do comment your "code"?
-
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