After reading my last journal entry, Ovid and I started talking about how to format source code. He prefers one blank line between the POD docs and its sub, and one blank line between the sub and the next sub (I think it was) over my keeping the sub and its POD together, and separating different subs with three blank lines.
Having this kind of discussion can easily become very unproductive and stupid if you just spew opinions. But it becomes interesting if you can avoid the "what" and instead drill down to the "why" of things. Being challenged about opinions is good because it makes you figure out the reasons behind them and hopefully it clarifies your thinking in some way. You may even change your mind (imagine that!).
I often find that whenever I need to explain why I do something it boils down to a principle or rule of thumb or other that I have picked up over the years. And if I can't find a rule of thumb, thinking about it may make me formulate one which is also a win.
The Principle of Proximity
In this case of where to put whitespace (or not), it is the Principle of Proximity. Since this issue is all about reading source code, it comes from the area of typography and visual design.
The Principle of Proximity tells you to put related items close together physically. Things that aren't related should be farther apart. The amount of separation between items or groups tells your reader how the material is organized.In short: Things that belong together should be together.
So this is why I don't like source to look like this:
}
=head2 run_safe($c, $sub, $fail_action, $fail_message, @rest)
...
=cut
sub run_safe {
....
}
=head2 class_to_moniker($class_name)
...
=cut
sub class_to_moniker {
...
}
To me, even with proper syntax highlighting that just blurs together into a grey goo. It's obvious from convention that the POD comes before the sub, but otherwise there isn't enough visible structure to it.
The Principle of Proximity is very similar to the concept of Perceived Affordance from Don Norman's The Design of Everyday Things. Translated to web design, this basically becomes: If it is a button, it should look like a button. and if it looks like a button it should be a button. Anything else will guide the user in the wrong direction.
Translated to source code: if things belong together, it should look like they belong together. If things look like they belong together, they should belong together.
In source code, the belonging is indicated by visual grouping, which is why I much prefer grouping the sub and its POD block into a visual unit, and separating the individual subs with vertical whitespace, like this:
}
=head2 run_safe($c, $sub, $fail_action, $fail_message, @rest)
...
=cut
sub run_safe {
....
}
=head2 class_to_moniker($class_name)
...
=cut
sub class_to_moniker {
...
}
See? Two things. At a glance.
One argument for not putting too much vertical whitespace between subs is that it limits the amount of code visible on the screen. But while I sympathise with that idea, because each individual sub is the unit of interest at a given time, they are generally to be understood in isolation from each other. Separating them visually only reinforces this notion.I've never added the additional newlines between functions, but you've convinced me to experiment with it for a while.
Re:I like your "why"
sigzero on 2008-01-07T00:58:32
Oh and that, of course, assumes you put your POD in with the code and not at the end of the file or in its own separate.pod file (which I don't do but have seen). Re:I like your "why"
jplindstrom on 2008-01-07T01:44:05
So what's your "why"?Re:I like your "why"
sigzero on 2008-01-07T17:33:08
I am not sold on anything by any means but I generally don't like a lot of POD intermixed with code because for me it makes it harder to read (call it "eye noise").
I like your way though and may try that. It may be easier to read it "blocks".Also,,,
sigzero on 2008-01-07T17:39:49
I tend to favor the PBP book practices and it recommends placing POD at the end of the file. I had no real reason to do any but.
… POD commands are supposed to go in a paragraph of their own, ie. you are supposed to have a blank line above and below every =foo line.
Re:Strictly speaking…
Ovid on 2008-01-07T09:05:29
Is this for technical or conventional reasons? I do recall that there were some older POD parsers that had issues with there not being a newline after the final =cut (yeah, that was real fun to debug), but I don't think that such an artifact is a good reason to disregard jplindstrom's proposal.
Re:Strictly speaking…
Aristotle on 2008-01-07T09:31:25
That’s how POD is specified. Interestingly, I see now that
=cutis exempt from this rule, at least insofar as it doesn’t have to be followed by a blank line.(This rule that POD is broken down paragraph-wise for processing is why Perl 5 POD is so terribly verbose for marking up lists, which is why I have stopped using POD as my personal document markup of choice and soon afterwards switched to Markdown, btw. I hear POD6 is going to do this much better.)
Having this kind of discussion can easily become very unproductive and stupid if you just spew opinions.
Well, this part of the post I agree with 100%
At work, I've already told jplindstrom and others that I don't care what the source code formatting rules are, so long as they're consistent and automated. There's no way in hell I want to enforce them manually, but even if I don't like them, I'll follow them since most (reasonable) programmers have at least semi-coherent styles and when people start getting petty about it, it grates on my nerves more than two-character versus four-character indent arguments.
Interestingly, I've proposed the "I'll do any format you want so long as it's automated" at several jobs now. Not once has this ever been implemented.
Re:Formatting
Aristotle on 2008-01-07T10:22:20
Heh. I chose mine in part because I can cajole perltidy into spitting it out… alas, not entirely:
I have a rule that a comma-separated list is either all on one line, or it gets bracketed/parenthesised and written one item per line. (Fat commas do not count.) Perltidy does not help with this.
The other problem is not due to perltidy, but because I don’t know how to deal with it: line-wrapping.
I have never found a satisfactory rule for how to break lines to hard-wrap them at a specific column. I find that no matter how it is done, readability always suffers unacceptably. It’s much worse if unwrapped code gets line-wrapped dumbly by the editor, of course. So I turn line-wrapping off (
:set nowrap), and I do occasionally let my lines run past 80 columns. But I do my best to avoid this manually, by measures such as factoring subexpressions into temporaries and the like.Funnily enough, even though that’s not something a pretty-printer will ever be able to do in my stead, simply telling it to never wrap lines works just fine for code that was written with this expectation.
Other than those (and a few niggly cases so rare that I can’t think of them off hand), my style is exactly what perltidy will produce with the appropriate settings.
Re:Formatting
jplindstrom on 2008-01-07T16:34:45
Your comma separated list reminded me that I have stuff to make that easier to reformat. Well, I see you use Vim, but maybe someone else will find it useful.Re:Formatting
jplindstrom on 2008-01-07T11:27:25
Yes, agreed. It's all about trade-offs, and when weighing consistency against arbitrary-layout-rule, consistency has a lot going for it.
But sometimes you can get two out of two.