Beefy Boxes and Bandwidth Generously Provided by pair Networks
Come for the quick hacks, stay for the epiphanies.

Re: On comments

by hsmyers (Canon)
on Dec 24, 2010 at 04:46 UTC ( #878952=note: print w/replies, xml ) Need Help??

in reply to On comments

Much of the last 10 or 15 years I've been brought in as a hired gun to 'maintain' (read fix) existing code. I follow a standard procedure. First I strip all of the comments. Then I reformat the code. I do the first step because I don't care what someone else thinks the code is going to do or should do--- all I care about is what the code does do. I make the second change purely for comfort. When I use one or the other of the various code for-matters, I match my own standard which increases the code's clarity at least for me. With these two tasks accomplished I have at least a chance to succeed!


"Never try to teach a pig to wastes your time and it annoys the pig."

Replies are listed 'Best First'.
Re^2: On comments
by JavaFan (Canon) on Dec 24, 2010 at 23:30 UTC
    I recently wrote a few modules for our company where the ratio of comments vs code was about 5:1. And the code wasn't complicated. Mostly finding some maximums and value switches in sequences, followed by changing some numbers.

    Still, I consider the comments to be very important. Sure, it's easy to see from the code that some numbers at the end of the sequence are changed - but without the comments, you will have no idea why it happens.

Re^2: On comments
by Tux (Canon) on Dec 24, 2010 at 13:23 UTC

    If the code is changing ownership to you, these are fine steps, though I wonder what removing comments that explain a reasoning for a choice of construct or flow would do you any good.

    If however the code is maintained by you just this time but is expected to be maintained by someone else in the near future, changing the style/layout would - for me - be a reason to fire you. Companies have (or at least should have) a company standard/policy. You - as a maintainer - should follow that strictly.

    Same for open source. Depending on how strict or how loose rules are set up, you should follow them. For me this is a reason to almost never contribute to GNU projects, as they want patches/code-chunks in their style, and as I think their style sucks, I don't write code for them.

    People giving me patches for my projects in their own style are reviewed and reformatted to match my style, because these are my projects. People not complying to my style is my major reason not to hand out commit bits.

    Enjoy, Have FUN! H.Merijn
      Since all of this happens on a copy of the original I fail to understand anything of your justification to 'fire' me. Did you fail to note the word 'fix' in parens? This means it doesn't work. If it doesn't work, comments are at best suspect and often completely misleading. Again the comment about copy allows me to format the code in any way shape or form I desire. I don't work for these companies, I'm brought in from the outside to put out a specific fire. Those things that help do that are good. Now at some point the error or errors will be found. That information, not quite a patch but close, will be turned over to those in charge of the code in question. So as I walk out the door, the only thing that will have changed will be that which didn't work. Note that if it needs comments as negotiated with those I turn the code over to, then I will be pleased to comment according to any standard they happen to choose. I've nothing against comments, I just don't want them in my way...


      "Never try to teach a pig to wastes your time and it annoys the pig."

Log In?

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

How do I use this?Last hourOther CB clients
Other Users?
Others about the Monastery: (6)
As of 2023-12-11 22:00 GMT
Find Nodes?
    Voting Booth?
    What's your preferred 'use VERSION' for new CPAN modules in 2023?

    Results (41 votes). Check out past polls.