

Patterns and Anti-Patterns in Code Comments - einhverfr
http://ledgersmbdev.blogspot.com/2012/08/patterns-and-anti-patterns-in-code.html

======
bediger4000
I have to disagree with the "signed comments" concept. Maybe if the comments
are one-liners, and the signature just initials like in the article. Just like
everything else, "signed comments" get abused by the "enterprise software"
types. How often have you see a comment that looks like this:

/* Changed to meet CR 19837xyz, H.B. Smith, June 12, 1999 */

That's a minimal signed comment in "enterprise software". Usually, there's a
huge flower box with required sections, few filled in, or at best marked
"N/A". And then the highly pompous signature. People only do that because it's
total CYA. Nobody will fault them for writing utter rubbish, and then signing
it.

Tracking who did what changes, and why, that's for version control. Flower
boxes, elaborate comment format requirements, and signatures, that just
demonstrates that you're not even using RCS-grade version control.

~~~
einhverfr
In that case, there's no reason to sign the comment. Signing adds very little
here. It's entirely optional. It's a simple, objective description of what has
been changed in the software, more like a footnote. However, if you are going
to offer thoughts about what code, perhaps offer suggestions as to where
things need to go, then signing is very important.

I really dislike seeing a comment that says "We OUGHT to X here" with no idea
of who wrote it.

Also anything can be abused. Cautions about what sort of abuse to watch out
for are very helpful.

------
mmahemoff
Just to comment on the presentation, imo this would be a good kind of pattern
to mostly demonstrate visually and with real-world examples, similar to the
new breed of UI pattern websites (e.g. <http://mobile-patterns.com/>)

~~~
k3n
That's a great reference, thanks!

~~~
mmahemoff
There's several more worth checking out if you search for "mobile patterns"
"android patterns" etc.

------
cjdentra
Synchronization to source and perhaps being able to detect when comments are
not current would be a great feature. How about associating comments to code
but outside of it sort of like a "source-aware" wiki?

~~~
mark_story
That idea kind of reminds me of the annotated source used for backbone.
<http://backbonejs.org/docs/backbone.html>

~~~
vineet
I love the philosophy behind the annotated source for backbone. But, there
seems to be something more going on with commenting - especially given that
the content of the backbonejs.org homepage is different from that of the
annotated source.

I guess the comments are meeting the needs of two different audiences (those
looking at just the api and those looking ay the code).

