News for hackers. Stuff that matters.
Re:Patterns and Anti-Patterns in Code Comments by bediger4000 on Thursday August 02, 2012 @11:22PM (#4332361)
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.

Re:Patterns and Anti-Patterns in Code Comments by einhverfr on Friday August 03, 2012 @12:35AM (#4332560)
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.

Re:Patterns and Anti-Patterns in Code Comments by mmahemoff on Thursday August 02, 2012 @10:11PM (#4332161)
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/)
Re:Patterns and Anti-Patterns in Code Comments by einhverfr on Thursday August 02, 2012 @10:12PM (#4332168)
Thanks. I was considering a couple of full source files but wasn't really sure how to work them into the presentation :-P
Re:Patterns and Anti-Patterns in Code Comments by k3n on Thursday August 02, 2012 @10:38PM (#4332239)
That's a great reference, thanks!
Re:Patterns and Anti-Patterns in Code Comments by mmahemoff on Friday August 03, 2012 @05:41AM (#4333289)
There's several more worth checking out if you search for "mobile patterns" "android patterns" etc.
Re:Patterns and Anti-Patterns in Code Comments by cjdentra on Thursday August 02, 2012 @10:42PM (#4332262)
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?
Re:Patterns and Anti-Patterns in Code Comments by mark_story on Thursday August 02, 2012 @11:01PM (#4332308)
That idea kind of reminds me of the annotated source used for backbone. http://backbonejs.org/docs/backbone.html
Re:Patterns and Anti-Patterns in Code Comments by vineet on Friday August 03, 2012 @12:34AM (#4332556)
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).

Re:Patterns and Anti-Patterns in Code Comments by vineet on Friday August 03, 2012 @12:29AM (#4332546)
Hmmm... this would be great especially for cases where you have documentation that applies to multiple methods or classes.

Ofcourse, the devil is in the details of getting it right.