in reply to Re^2: Centering Text with GD::Image
in thread Centering Text with GD::Image

avoid the indirect syntax in your own code and don't suggest its use to others.

While I agree with the advice, don't be too hard on people who use that notation for GD -- the GD POD shows indirect object notation in their SYNOPSIS and most (‡) of their code snippets where they show using the new or newFromXXX class methods, even when they show correct method-notation just above the example. Given that poor documentation choice, I can understand why users would pick up the indirect object notation (for those who don't know that indirect object syntax is just an alternate, they might reasonably interpret that the indirect object syntax is required for GD, since so many examples show that syntax).

‡: but not quite all: the code snippets in newFromGd2Part and gifanimbegin each show one instance of method-style notation. But those are the only two instances of ->new* that I could find in the main GD POD code snippets. The rest are all indirect object syntax.

--

edit: created issue rt://139961

Replies are listed 'Best First'.
Re^4: Centering Text with GD::Image
by kcott (Archbishop) on Nov 05, 2021 at 06:14 UTC

    G'day pryrt,

    By quoting me out of context — by removing the leading "please" — you've turned what was intended as politeness into what looks like a harsh command. Your first sentence, which includes "don't be too hard on people", strengthens that (incorrect) perception.

    There's a lot of poor code posted by CPAN authors; this doesn't mean that it should be blindly followed in cargo-cult fashion.

    The code in the SYNOPSIS of GD, to which you linked, does indeed use indirect syntax. It also has five package variables. I'd be reasonably confident that "please don't use package variables, use lexical ones instead" would not be greeted with "don't be too hard on people".

    Furthermore, module POD (and even perldoc code) is generally intended as an example. It's not littered with strictures, error checking, data validation, and so on. It is meant to show the guts of what's needed; not Perl Best Practices or anything like that.

    Bod has been here almost a year; he'll celebrate his first Monkday on Monday week. In that time, he's shown an extraordinary eagerness to learn. I applaud this attitude and, wherever possible, I've attempted to help him. There was nothing intentionally negative in what I wrote and, if you look at his reply, you'll see he took no offence (and, in fact, thanked me).

    — Ken

[reply]
      By quoting me out of context... you've turned what was intended as politeness into what looks like a harsh command

      That was not my intention. If that's how it came across, I am truly sorry. I wasn't trying to say that you were being rude or mean; but I can see that my use of "harsh" was too harsh on my side, so again, my apologies.

      My main point in that post was actually that the documentation encouraged coding practice that the perl documentation actively discourages -- which is why I went on to edit my post with the rt issue link.

      It is meant to show the guts of what's needed; not Perl Best Practices or anything like that

      I understand.

      IMO, there's a difference between POD not following best practices of warnings and strict, and POD that encourages the use of indirect object notation which is actively discouraged in official documentation. And it would be a simple enough change for the module developers to change those examples away from Perl-4 style indirect object notation which has been actively discouraged since Perl 5.6.0 in 2000. There are about 20-30 instances of = new or = newFromXXX, which would take all of 10 minutes to fix in the docs. (I am probably even going to put in a Pull Request against that issue).

      In the end, I think we agree on the general principle that it's better to avoid indirect object notation; and I'm sorry that I used the word "harsh" in describing your admonition against it.

[reply]
[d/l]
[select]
        IMO, there's a difference between POD not following best practices of warnings and strict, and POD that encourages the use of indirect object notation which is actively discouraged in official documentation.

        I agree entirely. Most code samples I see in POD are not presented as complete, runnable scripts. This is fine but it is necessary for the reader to understand it and realise that not all the code is necessarily present, including strictures.

        Conversely if there is some deprecated practice actually evident in the code sample as written, then that's a different matter.

        It might be useful to have a way to use Perl::Critic on the snippets within POD in order to catch some of these but I am not aware of a trivial method for doing so.

        🦛

[reply]
      In that time, he's shown an extraordinary eagerness to learn. I applaud this attitude...

      Thank you Ken for your kind words.

      The whole reason for being here in the Monastery is to learn. A year ago I could not have imagined just how much I would learn in a short 12 months! I am also brutally aware of how much my ignorance outweighs my knowledge. I am not a professional programmer. I run a company that has nothing to do with technology other than we use it across all areas of the business. I am an enthusiastic amateur who creates many of our internal systems and outward-facing marketing presence. In many ways, writing code is not the best use of my time. However, I enjoy it and it is useful when we need to make changes rapidly...I am thankful for having written our systems when I hear of other businesses calling up a developer and being told the lead time is several weeks.

      It is also part of our culture to push out and test changes very regularly. Having at least some development skills in-house certainly helps with this.

[reply]
        "I am also brutally aware of how much my ignorance outweighs my knowledge."

        I wouldn't worry about that one bit. The more I learn, the more I realise I don't know; and that pretty much applies to any subject.

        — Ken

[reply]
Re^4: Centering Text with GD::Image
by pryrt (Abbot) on Nov 05, 2021 at 19:43 UTC
    created issue rt://139961

    I put in a pull request for that issue, and within a couple hours, it was merged -- fast response! So the next release of GD will use the updated POD, no longer showing examples with indirect object notation.

[reply]

In Section Seekers of Perl Wisdom