Beefy Boxes and Bandwidth Generously Provided by pair Networks
We don't bite newbies here... much
 
PerlMonks  

Re^4: What makes a comment "obnoxious"?

by mr_mischief (Monsignor)
on Sep 10, 2007 at 01:57 UTC ( [id://637968]=note: print w/replies, xml ) Need Help??


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

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.

  • Comment on Re^4: What makes a comment "obnoxious"?

Replies are listed 'Best First'.
Re^5: What makes a comment "obnoxious"?
by BrowserUk (Patriarch) on Sep 10, 2007 at 07:52 UTC

    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.
      It sounds awesome. Unfortunately, it also sounds very tied to a particular dialect of a particular language. For K&R C or then ANSI C (heck, it's not hard to make one tool understand either, as the syntax isn't that different) you get a good return, because there's a lot of code out there and the structure is somewhat regular. It'd be even better for Lisp and most of its descendants.

      However, the strength of line-based source control is the same as the weakness you point out: its very generic method. A line-based patching revision control system is more efficient than storing a whole new version of every file with every change, and does not require the up-front investment of a language-aware revision system.

      People should, of course, not pass on maintaining comments and code because of the source control. They should, though, avoid making arbitrary changes against the style of the project.

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: note [id://637968]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others examining the Monastery: (8)
As of 2024-04-25 11:34 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found