Beefy Boxes and Bandwidth Generously Provided by pair Networks
Perl-Sensitive Sunglasses
 
PerlMonks  

Re^4: On comments

by mr_mischief (Monsignor)
on Dec 24, 2010 at 12:12 UTC ( #879031=note: print w/replies, xml ) Need Help??


in reply to Re^3: On comments
in thread On comments

In a lower-level language like assembly comments can be very useful in ways that would be unnecessary in higher-level languages. I know that's only relevant in a rare case, because assembly (at least assembly written by hand) itself should be a rare case. I also agree that the "good comment" that so many support is probably more rare than they suspect. I can think of one situation I already mentioned in this thread that was from real life in which a good comment could have really helped.

Replies are listed 'Best First'.
Re^5: On comments
by BrowserUk (Pope) on Dec 24, 2010 at 13:19 UTC

    I agree with you. Right up to the point when I don't :) That might sound trite, but it actually reflects reality of my take on this subject. And many others.

    I don't consider each separate new thread on this subject here a standalone argument to be won or lost, but rather just another round in an ongoing discussion that comes around again every few months, and has been doing so (for me) for the best part of 30 years. And my position has changed over those years; and still varies depending upon the language I'm using. In general, the higher level the language, the less frequently does the need for comments arise. As Perl is the highest level language I use regularly, I see less reasons here than in most.

    But my default position is, and has been for a long time, extremely simple: Don't comment.

    It all started from a passing comment [sic] by my first and best mentor in the commercial programming world. He was a mathematician and Fortran programmer. I was working on a fairly involved 6502 assembler project and he was charged with overseeing me and the code I produced, but had no experience of assembler at all; let alone the bits & bytes convolutions involved in interfacing a "toy" 8-bit microcomputer to a very expensive high speed OMR more usually hooked up to mini or mainframe.

    He was going though the motions of "reviewing" my code when turned to me and asked: "You do know that comments are optional don't you?" To which I replied, "Of course, but I wanted to make it clear what I was doing.". "You mean, you wanted to make it easy for me to read?". I nodded. "The trouble is, if you comment every line, I have to read every line." He then pointed out several sections of code, essentially while loops, that had a dozen or so nearly identical lines with nearly identical comments. His suggestion was that I replace all those comments with a one or two lines at the top describing the block, but in a Fortran-esque style.

    And he was right!

    Not only did it save me immense amounts of time coding--especially when it came to re-writing bits to correct bugs. It also saved him loads of time reading. We also found that by commenting in terms of a higher level language, it actually made both writing the code; and verifying it, far, far easier than using English prose. The higher level language was designed for doing that exact job. Unlike English prose.

    And the benefit that the default stance of "Don't comment" brings to the table is that you have to justify (to yourself) breaking that stance by adding a comment, rather than the pro-commenters stance of having to justify not commenting. This, IMO, leads to far better commenting, because only those comments that are truly useful get made. And by their rarity, their significance becomes all the more obvious.

    Where the reverse stance means that people tend to comment because they think they should, which leads to the significant comments (and often the code) getting "lost in the noise".


    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.

      I agree with you about commenting being the exception rather than the rule. I also agree with comments being small, seldom, and to the point being helpful. I also see the advantage to sometimes using a higher-level programming language to comment a lower-level one. However, I don't see how using a higher-level language rather than English prose would help in every case.

      I don't see, for example, restating the code helping someone to understand why it is important to zero-fill or zero-extend the high 32 bits of a 64-bit register when working in 32-bit mode on a hybrid 32-bit and 64-bit machine for security purposes. An explanation of why something is done really doesn't come from doing it again in a different way. When you really must explain why, explaining how does no help. Hardware vagaries and minute details of domain knowledge can be restated in many programming languages, but the reasoning behind the code is still a separate thing from the code itself.

        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.

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://879031]
help
Chatterbox?
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-02-25 07:11 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?
    What numbers are you going to focus on primarily in 2020?










    Results (108 votes). Check out past polls.

    Notices?