Beefy Boxes and Bandwidth Generously Provided by pair Networks
good chemistry is complicated,
and a little bit messy -LW
 
PerlMonks  

Re: What makes a comment "obnoxious"?

by tubaandy (Deacon)
on Sep 10, 2007 at 02:24 UTC ( #637974=note: print w/replies, xml ) Need Help??


in reply to What makes a comment "obnoxious"?

I'm not a big fan of lots of octarands in comments, but that's my preference.

This discussion got me thinking, though. For lots of different professions, there is a style standard that is followed for publications. The American Chemical Society has a style standard, the American Psychological Association has a different one, and I'm sure that other professional entities do as well (I used ACS and APA as those are 2 I've worked in and I could think of off the top of my head, not to leave anyone else out.) While I think folks generally abide by "It's good to comment your code for other's benefit", isn't this more something that should be discussed and agreed to in the community (if that is important enough to act on)?

I do realize the difference between professional publications and scripting or programming. I don't really have an answer here, just wondering what others think.

Update:I looked up "octarand", and poqui is correct!

s/octarand/octothorpe/

We used this term in grad school, apparently I shouldn't have blindly believed my research advisor. ;) Mea culpa, and thanks poqui!

tubaandy

Replies are listed 'Best First'.
Re^2: What makes a comment "obnoxious"?
by BrowserUk (Pope) on Sep 10, 2007 at 17:30 UTC

    The problem with assertions like "The American Chemical Society has a style standard, the American Psychological Association has a different one, ..." is the implicit assumption in that assertion that a) the chosen standard is the best possible for the purposes of the organisation involved; b) that everyone within the organisation agrees with the latter assertion.

    I have never encountered any single organisation in which any single best practice, guideline or law was universally accepted by those within the organisation, much less those without. In every case, and I really do mean every case, that I am aware of, there are always...which makes this assertion the exception to the rule...exceptions to every rule, guideline, recommendation or law.

    Yes. I know that last paragraph is a tautological nightmare, but read it slowly and think about it a while before dismissing it.

    Until human intuition, compassion and judgement can be encapsulated into a piece of software, we (those of use lucky enough to live in societies that at least purport to support free democracy) will continue to rely upon the human intellect to discern right from wrong, good from bad, expedient from right. Any mechanism, process or system of law that discludes the possibility of exceptional incidence; mitigating circumstances; and the fallibility of human judgement; is dogmatic.

    And dogma, is the root cause of all evil in world today. Just as it was yesterday. And will be tomorrow.


    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.

      And dogma, is the root cause of all evil in world today.

      Dogma is the root cause of all evil? That sounds pretty dogmatic to me.

      This is starting to remind me of the teacher who said that someone who cannot understand and argue the opposite side of their own position is merely an irrational fanatical (or something like that). So what's the other side of that argument, I wonder.

      Update: I think, actually, this comment is a bit more obnoxious than I intended. Sorry 'bout that. Add smileys to taste.

      I appreciate what you're saying here (and I did read it slowly and carefully :) ). There's another off topic discussion about the need to standardize aspects of communication via refereed journals. In the ACS and APA examples, the reference standards allow anyone (who knows the standards) to easily go and look up the references, and are part of the rules to publish in journals governed by these bodies. (Theoretically, depending on your library, access to materials, you know.) Same thing applies to standardization of communication protocols, etc.

      Again, these were examples that I had on the top of my head. Perl is great due to TIMTOWTDI, and there is no reason to change it, or to change comments. :)

      tubaandy
Re^2: What makes a comment "obnoxious"?
by papidave (Pilgrim) on Sep 10, 2007 at 17:04 UTC
    IMHO, the difference, I think, between professional publications and Perl programming is that the professional associations don't have a culture that states "TMTOWTDI". But that is precisely what makes this question interesting to me:

    • Since any comment style that the reader can comprehend is "acceptable", we are clearly straining at gnats. This is ok, because the camel is on my desk, not in my coffee cup. :)
    • If we all agree that this is a preference issue, the problem is equivalent to "What style is easiest to understand?" And, reading your preferences provides me with useful information about what people like/dislike.

    Having said this, perhaps I need to initiate a poll...

    -papidave

Log In?
Username:
Password:

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

How do I use this? | Other CB clients
Other Users?
Others chilling in the Monastery: (6)
As of 2020-02-19 17:35 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    What numbers are you going to focus on primarily in 2020?










    Results (84 votes). Check out past polls.

    Notices?