Beefy Boxes and Bandwidth Generously Provided by pair Networks
Syntactic Confectionery Delight
 
PerlMonks  

comment on

( #3333=superdoc: print w/replies, xml ) Need Help??
However, I don't see how using a higher-level language rather than English prose would help in every case.

Definitely not "in every case". And to be honest, these days I'd use a good macro assembler (directives .while etc.) to code most loops, branches and procedures, which does away with the need for the HLL "description". But back then, the assembler did little more than translate the opcode mnemonics to binary, and perform (non-nested) branch calculations.

Your 'security reasons' is an example(*) of when you should (ie. I would) justify breaking my basic "Don't comment." stance. It is a clear case of the exception that proves the rule.

My "Don't comment" stance has a similar power to simplify and clarify, as modern moves in governments to switch from 'Everything is secret unless we say it is not' to 'Nothing is secret unless we say it is'. There is no intention to endanger people or things by giving away everything.

Just a desire to ensure that (costly) security efforts to be concentrated upon those things that need it. Oh, and if by-the-by, it prevents a few politicians and civil servants from hiding their laziness, gross incompetence or worse, behind layers of "need to know", so much the better.

And that's my take on comments. If you've justified the addition of a comment in a piece of otherwise sparingly commented code, you can bet your bottom dollar I am going to give it my full attention.

But by my reckoning, there are about 7 or 8 significant comments in this, but I challenge anyone to find them in a hurry, so lost are they in a morass of unnecessary, irrelevant or downright misleading thoughts, feelings, opinions and speculations.

(*)It is hard to tell from such a brief description of a real situation, but I actually, I still might not comment it. From my interpretation of your description, I would probably opt for self-documentation in the form of a macro: Say SEC_reg-zero <reg>; or SEC_reg-signExtend <reg>; and the detail of the security implications would be detailed once in the macro definition.


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.

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

Title:
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?
    Username:
    Password:

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

    How do I use this? | Other CB clients
    Other Users?
    Others chanting in the Monastery: (4)
    As of 2021-04-20 07:30 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      No recent polls found

      Notices?