Code Commenting Conventions

[piranha]

I have heard instances where source code is released, and then there are complaints about swearing and being rude.

My question is, what are the basic laws of code commenting (aside from doing it more than less and being helpful)?

Whats wrong with saying "The stupid compiler gets angry at cleaner looking code so we must make it ugly...>:("

What about jokes? Something funny?

-JL

[JackScott]

Linus swears in his comments. So do I.

As for jokes, I like them. They lighten the mood, especially if they are informative as well.

I usually include more function headers and so on than comments; I find that if you know what a function does, how it does it either isn't relevant, or should be immediately obvious. If it isn't either of those things, the function needs rewriting.

[piranha]

Cool. Some comments in my un-committed code have swearing, I was wondering if I should clean it up.

-JL

[Combuster]

The only time I know I put swearing in my code is when I encountered a glitch in the VB5 compiler. Somehow the optimizer was messing up a tight file read loop so that compiled versions would always crash with a overflow. Adding a call to an empty function fixed it. The nastiest comments I ever wrote are around there.

I tried finding swear words in my kernel, but how much i insulted the hardware at some points, it never got across the keyboard cable

[suthers]

The only time I know I put swearing in my code is when I encountered a glitch in the VB5 compiler. Somehow the optimizer was messing up a tight file read loop so that compiled versions would always crash with a overflow. Adding a call to an empty function fixed it.

Yah all my 'errors' are my compilers fault too
Jules

[Solar]

Some fun may be poked in comments, IMHO, but you have to remember the possibility of someone reading your code who is much worse at the language.

As I wrote in a coding style guide once, "the best pun backfires if it takes the guy reading your code additional time to figure out what you meant".

[Dex]

You must be carefull with spellings, as i am a very bad speller and when people download my code, you do not get any feedback, other than this and that as not been spelt right.

[Candy]

No comments here, unless there's something that can't be expressed in the program (such as a malfunctioning compiler, a non-functional requirement or something similar). I've commented to illustrate standards compliance, bugs in the compiler leading to awkward code, very very awkward constructions (Duff's device was the reason for commenting once, after checking whether a colleague would trip over it) and to indicate the reason for some odd constructions.

[Telgin]

I honestly never expect anyone to end up reading any comments I actually make in my code, so I suppose in the back of my mind I write that way too.

That said, I do still write comments for my own use. Since I don't swear in mundane (or even most exceptional) circumstances, I've never done so in a comment. I've been frustrated at code not working before, but that never makes it into the comments.

As for jokes and the like, I can't recall ever inserting anything like that since my comments are usually one liners that do little more than serve as bookmarks or unnecessary restatements of what the code does. Function headers on the other hand I do put in with a little more effort, but I still can't recall putting in a joke or anything.

[AJ]

I used to just comment when I thought something wouldn't be completely clear if I re-read my code.

Recently, I have discovered Doxygen, though, so I am starting to go through my code adding comments to let Doxygen generate documentation. If my kernel gets really big, this should be a good timesaver later.

Cheers,
Adam

[JamesM]

I comment most lines of my code. I'd say that 30-40% of the text that I write is comments.

I find it helps me work out what my algorithm is doing, and more specifically if it is broken.

example: in my code, looking through it I see "x&0x1000". Now - did I mean that? is it part of some algorithm? or did I mean "x&0xFFF", and there's an as-yet undiscovered bug?

Documenting comments would help to disambiguate that situation.

[CmpXchg]

I heard a joke that if you remove all the swear comments from the Linux sources, you can free up around 50k of disk space

[madeofstaples]

I usually include more function headers and so on than comments; I find that if you know what a function does, how it does it either isn't relevant, or should be immediately obvious. If it isn't either of those things, the function needs rewriting.

Not necessarily, consider this strlen implementation. It's neither obvious how this function should work, nor is it irrelevant (it's architecture-specific), yet comments do a nice job of explaining WHY this implementation is better than an obvious/irrelevant one.

In such cases, I think the lengthy comments in that example are somewhat-called for, I always try to be detailed when I comment so that when I come back to a project, I don't have to look up all the references (though I still keep those, too). Though, admittedly the example is probably a bit more than I would write, haha.

Also, I find that I am REALLY glad if I take the time to make a quick ascii-art depiction of something (such as a memory diagram), because human psychology postulates that we have two key parts of our working-memory (short-term memory, sorta)--the visuospatial sketchpad (visual short-term memory) and the phonological loop (short-term auditory memory). Studies have shown that if we utilize both of them at the same time, we more easily consolidate memory (store in long-term) and more easily recall related items, which translates to increased productivity.

[DeletedAccount]

Comment as much as you can, but only when it is relevent . But ideally the documentation should contation at least the following
a) Major Data Structures and variables b) Your rationale for choosing the above data structures .
eg

Code: Select all

int i = 0; // declare a variable i and assign zero to it

Comments like the above are pratically worthless and wastes space as well as time.

Regards
Sandeep Mathew

[AdHawk]

Seems to remind me of comments in the Windows Source for some reason:

http://www.kuro5hin.org/story/2004/2/15/71552/7795


Lots of interesting comments pulled out for you to read there. Linus uses swear words in his kernel, so do the windoze guys. It seems everyone does, so i wouldn't worry about it too much.