Beefy Boxes and Bandwidth Generously Provided by pair Networks
Keep It Simple, Stupid
 
PerlMonks  

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!

--hsm

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


Comment on Re: On comments
Re^2: On comments
by Tux (Monsignor) 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...

      --hsm

      "Never try to teach a pig to sing...it wastes your time and it annoys the pig."
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.

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others surveying the Monastery: (7)
As of 2014-07-25 04:19 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    My favorite superfluous repetitious redundant duplicative phrase is:









    Results (167 votes), past polls