Beefy Boxes and Bandwidth Generously Provided by pair Networks
Don't ask to ask, just ask

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
I have read Programming *is* much more than "just writing code". and it's clear that we come from diametrically opposite points about comments, which is fine. If we were working on the same team we'd need to find a compromise. I'm going to use the rhetorical tool I mentioned a while back in the node about "agressive argument" (Re: What is "aggressive" argument?) to defuse the discussion, which feels a little heated to me: since it is at least partially a matter of taste, this is one of those arguments that can't be definitively "finished" or "won", only abandoned - and I think that this is probably the proper point for me to do that. This is not saying "I'm right" or "you're wrong", just "we're not going to agree about this, I think".

It's possible that I've simply not clearly stated the assumption I'm working from: comments don't actually affect the logic of the program, Smart::Comments aside - but they do affect the logic of the programmer, and what he or she will decide to do.

Intentions, political considerations, external dependencies, and other similar factors that have nothing to do with the local code that's on the page (but everything to do with the context in which it was developed and in which it must run) are important, and that not making sure they are known at the exact point where further decisions need to be made in the source code will increase the chances of those decisions being wrong, perhaps catastrophically so.

I personally think that comments are the best way to do that: right at the code that was affected by the external circumstance (some other obscure code called it, in the case of the debugger, or that variable really does have to be zero or we have a remote root exploit in the Linux kernel source). Is there a better way to communicate that kind of thing at the point of decision: at the place in the code that might be changed without a signpost that doing so would be Bad? Remember, I'm not asking you to make the code clearer; I'm asking you to make the context clearer. What's the best way to do that?

I think we agree that this non-local-code context is important, and difficult to communicate effectively. I would be very interested to hear what ways you use to get all that messy not-code stuff across to "the next victim".

(Edit: spoiler that shows the comments from wasn't working for me, but is now...go figure. Minor wording changes for clarity.)

In reply to Re^4: On comments by pemungkah
in thread On comments by pemungkah

Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":

  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?

    What's my password?
    Create A New User
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others musing on the Monastery: (4)
    As of 2020-10-31 19:56 GMT
    Find Nodes?
      Voting Booth?
      My favourite web site is:

      Results (291 votes). Check out past polls.