in reply to What makes a comment "obnoxious"?

Hmm .. put me down for another downvote (not on your node) on the line of hashes. Although, I admit to being hypocritical on that, since ever source file I check into version control has something like 

#!/usr/bin/perl -w
##********************************************************
## Copyright (c) 2004, 2005 That Company
## Copyright (c) 2006, 2007 This Company
##********************************************************
## $Id: SomeProgram,v 1.24 2007-08-23 13:37:05-04 talexb Exp $

[download]
at the top of each file. That's just what the company standard is -- but that's the only place I have lines of hashes. It's too noisy, but, as has been mentioned, it's a personal taste thing.

At least it wasn't a 'flower box' comment -- they were stylish in the late 70's, and not since then. Thank heavens -- they were truly ugly, and a pain to maintain.

Alex / talexb / Toronto

"Groklaw is the open-source mentality applied to legal research" ~ Linus Torvalds

Replies are listed 'Best First'.
Re^2: What makes a comment "obnoxious"?
by amarquis (Curate) on Sep 09, 2007 at 14:31 UTC

    Flower box comments? Do you refer to this:

    #############################################
#     I am a very difficult to maintain     #
#  comment, why did somebody do this?       #
#############################################

    [download]

    When I start maintaining somebody else's code I usually adopt their comment style for the sake of consistent code. If these kinds of comments are there, though, they go out the window. Even typing that was sort of a pain.

    As said above, I think having a consistent pattern is more important than what that pattern actually is. If everything is the same, it's usually simple to go in and write a little script to make it look the way you want.

[reply]
[d/l]

      Yes, that's a flower box (shudder).

        When I start maintaining somebody else's code I usually adopt their comment style for the sake of consistent code.

      And that's an excellent idea. It's unbelievably tempting to go in and start making wholesale changes, but that's wrong for a couple of reasons:

      • You just know you're going to break something (and tests may or may not catch that -- but why risk it? Oh, you don't have tests?) ;)
      • It's not in the budget ("Um .. you've been reformatting comments for the last four days?")
      • You may just end up confusing yourself further -- your brain's figured out how the old code worked, but now that it's in a new format, you have to learn it again. And if the original author comes back, a) they won't be happy, and b) it will take them longer to 'reload' what the codes does since it's not in 'their' format anymore.
      And you've nailed down why -- it's most important to maintain consistency in a piece of code. A module that shows multiple styles is a module that's destined for failure -- it's a Tower of Babel thing.

      Alex / talexb / Toronto

      "Groklaw is the open-source mentality applied to legal research" ~ Linus Torvalds

[reply]
        You left out one of my favorite pet peeves about reformatting comments in another's code: patches.

        If you're working on some code and submit a patch that improves something, that's great. If you submit a patch that makes a one-line code fix and the patch is 50 lines long, that's a pain.

        Guess what one of the primary, if seldom mentioned, rules of submitting patches to a project is? Make things easy on the lead maintainer. If a project has 20 files, and your patch makes someone undo 49 lines of comment changes in one file to ensure that the comments match the other 19 files, that's more work than is necessary, and your patch is likely to go to /dev/null. Yes, the maintainer could take the time to figure out where the one meaningful change is, but so could the author of the patch.

        Even in source control within a team, if your store is patch-based then you're making a mess of revisions by fighting over comment style. If it's not patch based, you could still be making extra check-ins that are unnecessary and screwing up consistency between files.

[reply]

In Section Seekers of Perl Wisdom