in reply to Re: Lower-casing Substrings and Iterating Two Files together
in thread Lower-casing Substrings and Iterating Two Files together

Were I maintaining such code I would definitely want a comment along the lines of: 
    # ord(" ") = 32 and flipping that bit lower cases ASCII.

[download]
Otherwise++.

Replies are listed 'Best First'.
Re^3: Lower-casing Substrings and Iterating Two Files together
by BrowserUk (Patriarch) on Dec 27, 2008 at 16:14 UTC
    ord(" ") = 32

    If it were my code, I think ord(" ") = 0x20 or even ord(" ") = 0b0010_0000 might be clearer, but that's essentially why I rarely comment the code I post. We tend to write comments that mean something to us, rather than others.

    My antisipation (hope!) is that what I post will rarely be used verbatim in other peoples programs. Indeed, I quite often leave the code deliberately shy of being a complete solution to the OPs question so that they will have to adapt it to their use. With the intent that anyone basing their code upon my postings, will first play with it a little to ensure that they understand it, and then adapt it to their needs.

    At that point they can adjust the coding style to their preferences or local requirements, and add whatever comments they think most appropriate.

    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.
[reply]
[d/l]
[select]
      Any of those comments would be better than none. Because right now there is no way from the code to understand that you meant to upper case letters. Without which knowledge it would be hard to tell whether you intended G and T to give you W or whether that would be an accident.
[reply]
        Any of those comments would be better than none.

        Sorry, but I disagree. The post contains a full explanation of the algorithm involved and additional comments in the associated snippets would be redundant. Even dangerous. And taking those snippets out of context of the post, does it a disservice.

        What you are suggesting is that if a programmer cribs a reference work--say AoCP--that they should incorporate into their code, the same comments as the author of that reference, incorporated in theirs. Knuth's comments for his MMIX code probably won't make a great deal of sense, if applied to a Perl or Haskell implementation.

        hard to tell whether you intended G and T to give you W or whether that would be an accident.

        In the context of the post, the intent is clear. Taken out of context, pretty much anything can be misinterpreted. And trying to write comments that could never be misinterpreted regardless of what context you dropped them into is an exercise in futility if ever I heard one.

        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.
[reply]

In Section Seekers of Perl Wisdom