Slash Boxes
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

jplindstrom (594)

  (email not shown publicly)

Journal of jplindstrom (594)

Sunday January 06, 2008
03:59 PM

Cohesive source formatting

[ #35310 ]

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)

sub run_safe {

=head2 class_to_moniker($class_name)

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)
sub run_safe {

=head2 class_to_moniker($class_name)
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.

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
More | Login | Reply
Loading... please wait.
  • I've never added the additional newlines between functions, but you've convinced me to experiment with it for a while.

  • I am not sure I would do it that way but at least I can understand why you do.
    • 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).
    • So what's your "why"?
      • 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".
      • 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.
  • One reason I prefer extra blank lines everywhere simply has to do with how I navigate in vim: I use curly brackets to say "jump to the next line". It's enormously useful, give it a try.
  • … 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.

    • 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.

      • That’s how POD is specified []. Interestingly, I see now that =cut is 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

    • Heh. I chose mine in part because I can cajole perltidy into spitting it out… alas, not entirely:

      1. 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.

      2. 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 col

      • 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.
    • 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.
  • The perceived affordance idea may be similar to
    the idea of leveraging natural language.

    The difficult thing is that though the
    relationship between statements is like the
    relationship between sentences in written text,
    the relationship between subs is not like the
    relationship beween paragraphs. A program is
    differently structured than an essay, or other
    written work.
    Some higher order graphic organizers become