Which tricks, hints or shortcuts do you use regularly when you document your sourcecode?
What type of comment does help you most (or is most desired) when looking over a piece of sourcecode?
For an example, we always use date, shortcut of name and a +, -, * (added, deletet/commented, modified) and then some description:
// 30.04.09 PL+: blablalba
If it's something simple, I don't usually bother with a date. I can get that from source control later. I just say what it does: "Get the user's meta data"
If I'm tampering with someone else's function at work, I usually leave a message like:
// 4-30-2009: (Steven) Modified to make it less prone to DROP all tables
If I think a piece of code is going to be confusing, I write some conversational comments in addition to the "here's what line X does" inline stuff:
/* Bear with me, this is going to get stupid-hard to follow
First we get the ID of the thing
Then we get the children of the thing based on the ID
Now, for each child, if that child has a date parameter that
falls on a full moon, we return void so that otherFunction
knows to take cover.
Otherwise, delete the child and never look back
*/
Additionally, I use comments as pseudocode as I start building a new method or class. It's the code equivalent of talking to myself (it pretty much looks like that last comment block). It helps immensely with wrapping my brain around the process I'm trying to implement. The comments themselves may end up modified or replaced later, but it speeds up my development process and I've noticed significantly fewer bugs in the code I write this way.
When reading comments in a program I've never seen before, dated modification comments are pretty useless. I wasn't there to see the original, so it's not really helpful to know why the new code is the way it is. That's really what commit messages are for.
Much more useful (to me) are humanized messages: "Get the frame buffer and clear it so we have a blank slate before drawing." Something that gives purpose, technical detail and context all at once. The best comments have the potential for education as well as documentation: here's what we're doing, and here's why.
what i usually do is put
// John Doe - 2009-04-25
// Did some refactoring because of some reason
I find that it helps me remembering who, when & why.
The place for meta data pertaining to when and why something was changed is your source control system. As always, there are exceptions.
Comments shouldn't explain what code does - the code should clearly describe its function. If the code does not clearly describe its function you should look at fixing the code.
Comments should be reserved for helping the reader understand why the code is the way it is. If you had to choose between A and B, comment on what the choices were and why you chose A over B iff the choices and your decision are not immediately obvious.
Be certain to use comments to explain your choices particularly if your choice appears, on the surface, to be odd. For example, if, when faced with method A or method B, 99% of people would use method A and you choose method B because there is an odd edge case that makes method B more appropriate, make this very clear so as to prevent people reverting to method A.
The notable exception to commenting on when and why things were changes are bug fixes. Obscure bugs are inevitably fixed, or worked around, with some obscure code. The code may appear redundant but should not be changed otherwise the bug will re-surface. Make these cases exceedingly clear in your comments.