Fog Creek Software
Discussion Board




table of categories for comments

I'm interested in applying an homogeneous comment style in my programs. I am not just talking about the form (important for searching), I am talking about the content.

Have anyone got any table of categories for comments? I mean, I can identify some basic types of coments, but when I try to add more I get confused because some comments would belong to more than 1 category. :/

As pointed in the tread "How should I comment code?", everybody seems to agree on:

- comments have not to be obvious, have to give some valuable information other than code itself for a competent reader
- comments have to be helpful for future coders using it or maintainers fixing or adding code
- comments may help to understand code
    why the code is this way?
    why is this function calling necessary?
    what this thing is trying to accomplish?
- comments may help to correctly use code
    this module has to be used this way, not that way

So far, these are my 6 categories:
HAS_TODO    SUG_TODO    TRICKY      KNOWNBUG    INFO    no mark

Explanation;
>HAS_TODO: things that *need* to be completed/fixed

>SUG_TODO: things that should to be implemented,  (ex. suggestion for improving some thing: speed, space, readability, arquitecure, etc...)

>TRICKY  : explanation of some obscure or dark part of code

>KNOWNBUG: when there is a bug, it's good to know, so we mark it on code

>INFO    : important information doesn't fit into the categories above, ex. about how has to be used a module, a function, or list of errors returned, etc. This is the category for the big part of comments *before* code lines, the thing everybody has to read if interested in knowing/using code.

>no mark : not so important information doesn't fit into the categories above. I guess this is the category for the big part of comments *inside* code, the thing only people who have to enter inside code need to read.
It's "low[est] level info".



But I find this list too short, although it's easy to choose a category when you have got a comment, this "easy of use" feature is very important (I can not spend 5 minutes trying to choose wich category is the best for my last comment)

Any ideas about completing/changing this list?
Any other comment categories lists you use?

PS. Sorry for my English.

Ross
Sunday, May 04, 2003

The most important one is CAVEAT PROGRAMMER

Which essentially means screw with this and you're dead.

If I'm fixing bugs in someone else's code then I tend to prefix my comment with SPL:  just to show its me that did it.  Unless its relevant though a bugfixing comment goes at the top of the file rather than at the point of the fix.

Revision Histories at the head of files seem to be going out of fashion though which is a pity.

Simon Lucy
Sunday, May 04, 2003

How about -

// DESCRIPTION:
// IN:
// RETURNS:
// PRECONDITION:
// POSTCONDITION:
// LOOP INVARIANT:

Just kidding.  I'm taking a class right now and just spent the last 2 hours going back and documenting my code to the teacher's guidelines.  I'd be happy not to write another loop invariant in my life.  I should say, though, that I have seen preconditions and postconditions documented in some libraries and found them helpful when it's not obvious.

Also, I've seen some code that needs this tag:
// IDKWTFTDBIGIOTI:  (I don't know WTF this does because I got it off the internet)

Nick
Sunday, May 04, 2003

How about SUX_TODO ?

anon
Sunday, May 04, 2003

Here are some of the things I document.  You chew on your pencil and come up with category names.

Why.  Why did I choose this pattern, why did I subclass instead of use a composite, why did I use an array instead of a Vector or ArrayList.

Assumptions.  This method assumes ____.  This call assumes ____.

Dangerous ground.  Warning: if you play with this code you risk a self.foot.shoot incident.

Futures.  This probably ought to be refactored in the future.  This could stand some better error-checking.  If you subclass this always override someMethod().

Hidden traps.  This looks like a performance problem, but benchmarking shows I/O is the limiting factor.

-Thomas

Thomas
Sunday, May 04, 2003

Huh? I thought you would just create a column for "category" and this way you could have an unlimited number of categories.

That column would have numbers, and those numbers would map to a seperate "categories" table with just two columns (maybe more)

table: comments

comment_id | category | comment
1 | 2 | "user text here"

table: categories

category_id | category_name

1 | inquries
2 | has to do
3 | tricky stuff

this allows for unlimited categories & user management of categories.

Or am I missing the point here?

www.marktaw.com | I say no sigs.
Sunday, May 04, 2003

"www.marktaw.com | I say no sigs", errr, the point is not how to create/design/implement the table. I am talking about which categories would be meaningful and useful for commenting code.

Ross
Sunday, May 04, 2003

OH. See, I wasn't paying attention.

www.marktaw.com
Sunday, May 04, 2003

Not a bad idea. I would shorten the tags. I don't want to step on your toes, but SUG_TODO is pretty awkward, at least to my eyes. Try "need:"  (need to have), "want:" (nice to have - NICE?), "tricky:", "bug:". "bug:"s are probably best tracked on the bug list, if you have one.

INFO should be so common and widespread that labeling it should be worthless. Another category for "incomplete spec" or "need more definition" might be useful. "spec:"?

TRICKY I would interpret as pretty much the same as the other poster's CAVEAT. However, I think it's far better to say "Even though we have a tree model and a node sub-class for the JTree we keep our own model here because the super class already uses arrays, plus we need OCO links on the graph but not the tree..." This is soooo much better than "Touch this and you will DIE!!!" or even "tricky: build another model just for the graph"

I use "tbd:" (to be devleoped) as an all-purpose marker - usually things I don't want to get hung up on at the time but will need to revisit.  I find it useful.

Jim S.
Monday, May 05, 2003

The actual cases of CAVEAT I've seen have been more mystical, more in the nature of 'look this works, we've tried a bunch of other ways and the stack always implodes just don't touch it.'

Simon Lucy
Monday, May 05, 2003

Of course, the size and style of the tags would be choosen shorter, and it depends too on language.


Jim S., can you explain a little bit about category "incomplete spec" or "need more definition" ?
Some example?

Ross
Monday, May 05, 2003

*  Recent Topics

*  Fog Creek Home