nysus has asked for the wisdom of the Perl Monks concerning the following question:

So I thought I'd make a contribution to a Perl module. Figuring I'd start easy, I thought I'd make some improvements to the tutorial for Dancer2. Of course, nothing is easy when you are a clueless bastard. Sigh.

So anyway, this is the file I wanted to contributed to: Dancer2::Tutorial. I notice the lines are all wrapped neatly with 83 characters being the longest line. Is this some convention for POD code? Also, there is no space after the last word in each line of the paragraphs. So I'm assuming some kind of POD generator was used to create the document? I searched through perlpod quickly but nothing jumped out at me with regards to the length of lines or spaces after the last word character in a line.

$PM = "Perl Monk's";
$MCF = "Most Clueless Friar Abbot Bishop Pontiff Deacon Curate Priest";
$nysus = $PM . ' ' . $MCF;
Click here if you love Perl Monks

Replies are listed 'Best First'.
Re: Max line length convention in POD?
by Dallaylaen (Chaplain) on Dec 06, 2017 at 05:03 UTC

    Not sure about Dancer devs. Maybe they use perltidy of similar tool before committing?

    Whitespace at line end is generally considered bad because it leads to confusing diffs and may even break a merge, which is quite annoying. I use a pre-commit script that prohibits that, but that's just me.

    I also try to keep my lines' length below 80 chars. And I try to align sentences with lines because that leads to smaller diffs when fixing grammar/typos.

    But that doesn't matter that much as POD lumps subsequent lines together and formats the whole paragraph. Unless, of course, one is selling 24" monitors for a living.

[reply]
      Maybe they use perltidy of similar tool before committing?

      Apparently so and it sets --maximum-line-length=79 so there is an enforcement present. Whether that is run on pure-pod files such as the one nysus is working with is a different matter because the maximum line-length in Tutorial.pod is indeed 83 (plus the EOL).

      Update: but only 3 out of the 661 lines in Tutorial.pod are over the 79-character limit so perhaps it should be enforced here. Maybe ask the Dancer devs on IRC for clarification?

[reply]
[d/l]
        > it sets --maximum-line-length=79

        I'd even reduce line length on pure PODs.

        A little googling shows that normal print publications tend to limit pure text lines between 45 and 65 characters.

        This makes sense, since readability depends on easy eye movement and minimized hassle to find the continuing line.

        Extending this to 70-80 for code is also sensible since

        • indentation adding whitespace to the left and
        • low density of statements per line
        still allow to move the eye fluently without loosing the line.

        Consequently dense paragraphs in POD should be limited to 65 at most.

        Couldn't find a setting for that in Perl::Tidy , but it should be possible in emacs.

        PS: I have to admit that "hanging" comments on the right make this calculation more complicated.

        Cheers Rolf
        (addicted to the Perl Programming Language and ☆☆☆☆ :)
        Wikisyntax for the Monastery

[reply]
[d/l]
Re: Max line length convention in POD?
by LanX (Saint) on Dec 06, 2017 at 12:08 UTC
    Keeping lines under 80 characters to improve readability is a universal style convention, not only for POD or Perl. (Update: or even programing)

    Cheers Rolf
    (addicted to the Perl Programming Language and ☆☆☆☆ :)
    Wikisyntax for the Monastery

[reply]
Re: Max line length convention in POD?
by ablanke (Monsignor) on Dec 07, 2017 at 09:36 UTC
[reply]

Back to Seekers of Perl Wisdom