in reply to Re: What makes a comment "obnoxious"?
in thread What makes a comment "obnoxious"?

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.

Replies are listed 'Best First'.
Re^3: What makes a comment "obnoxious"?
by talexb (Chancellor) on Sep 10, 2007 at 00:27 UTC

    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]

        And therein lies the rub with line-based source control software. It ceases to just be a tool for managing and documenting what the programmer does and begins to dictate what the programmer can and cannot do.

        No longer is the maintenance prgrammer just concerned with making changes to fix bug or add new features, they also have to ensure that the do not 'upset' the source code control trail by making 'unnecessary' changes. Hence comments get left unchanged and go out of date; badly formatted code, incorrect indentation et al. must be left uncorrected. Obvious refactoring gets left undone if it is percieved to affect too large a portion of the codebase.

        Not always and not everywhere, but "maintaning the integrity of the VCS change history" can take on too great a significance and become a major influence on what gets done and what does not.

        20 years ago, I got to play a little with a piece of source control software that understood the C language syntax, and maintained projects at the language structure level. For example, if it was desirable to move a function from one file to another, the change history reflected that as the function having been moved, not the deletion of a bunch of lines from one file and the addition of a bunch of lines to another. And if a function was renamed, that was logged as the renaming of the function, and when commited, it threw up all the points of use of that function as conflicts that needed to be resolved before the commit would be accepted. Comment blocks were seen as single entities, and were 'attached' to the code they documented. They either moved with that code, or had to be deleted if the code was deleted.

        Now that is source control.

        Unfortunately, the company that wrote it went to the wall. They were simply unable to sell it, because it was too radical. People are too wedded to their 30 year old line-based tools and do not want to change.

        Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error.
        "Science is about questioning the status quo. Questioning authority".
        In the absence of evidence, opinion is indistinguishable from prejudice.
[reply]

In Section Seekers of Perl Wisdom