Top level blocks and indentation

[Anno Siegel]

Top level blocks, that is, blocks at file level, serve many useful
purposes. An example is, in a module file, a related module or class
you want to incorporate in the main file. It rightly belongs into a
BEGIN block. Another example is a test file (t/*.t), where tests often
form groups. It is useful to put each group in its lexical space, which
means that most of the file is inside one top level block or another.

In such cases, indentation comes as a nuisance. I have taken to using
double braces, '{{' and '}}' to delimit top level blocks that aren't
indented. I'm using them because the don't appear "naturally" in Perl
(or do they?) and they don't hurt (or do they?). I also hope to say
something like "Yes, this *is* a block. I'm still not indenting", but
that is perhaps hoping a bit much.

The main question is, of course, how much does the lack of indentation
hurt? I don't notice more block structure mixups in sources where I'm
using that style, but then I'm biased. I did notice more mixups when
trying to *nest* double braces, so I'm not totally insensitive. Never
nest them, by definition double braces only apply to top level blocks.

In any case, before I release any code in this style to CPAN, I'd like
to test the waters and ask if that would, umm..., get me talked about.

If anyone cares to take a look at some code, I have put up two examples,
a module and a test file, under

http://www.tu-berlin.de/zrz/mitarbeiter/anno4000/clpm/double_brace/Module.pm
http://www.tu-berlin.de/zrz/mitarbeiter/anno4000/clpm/double_brace/test-file

Please, these are only to look at. They are taken as-is out of some
ongoing work. I'm reasonably sure they compile, but that's it. (And
don't anyone *dare* tell me it's undocumented, man do I know it

Anno

 

[James Willmore]

On 22 Nov 2003 17:07:14 GMT
(e-mail address removed)-berlin.de (Anno Siegel) wrote:

If anyone cares to take a look at some code, I have put up two
examples, a module and a test file, under

http://www.tu-berlin.de/zrz/mitarbeiter/anno4000/clpm/double_brace/Module.pm
http://www.tu-berlin.de/zrz/mitarbeiter/anno4000/clpm/double_brace/test-file

Please, these are only to look at. They are taken as-is out of some
ongoing work. I'm reasonably sure they compile, but that's it.
(And don't anyone *dare* tell me it's undocumented, man do I know it

I looked and have the following opinion - just take the comments as
opinion and nothing more.

You're method is a lot like getting the first new model of a car -
some will embrace the change and others will long for the good olde
days and question the change. I'm sitting on the fence (and boy does
my butt hurt ) I can follow the code, but the "accepted method of
indenting" filtering device in my brain is flashing red and saying
"Something is wrong".

If it were me, I'd do indenting so I can understand what's going on,
then run perltidy againist the code to make it "acceptable". But
that's me

--
Jim

Copyright notice: all code written by the author in this post is
released under the GPL. http://www.gnu.org/licenses/gpl.txt
for more information.

a fortune quote ...
Distinctive, adj.: A different color or shape than our
competitors.

 

[Tassilo v. Parseval]

Also sprach Anno Siegel:

Top level blocks, that is, blocks at file level, serve many useful
purposes. An example is, in a module file, a related module or class
you want to incorporate in the main file. It rightly belongs into a
BEGIN block. Another example is a test file (t/*.t), where tests often
form groups. It is useful to put each group in its lexical space, which
means that most of the file is inside one top level block or another.

In such cases, indentation comes as a nuisance. I have taken to using
double braces, '{{' and '}}' to delimit top level blocks that aren't
indented. I'm using them because the don't appear "naturally" in Perl
(or do they?) and they don't hurt (or do they?). I also hope to say
something like "Yes, this *is* a block. I'm still not indenting", but
that is perhaps hoping a bit much.

This sounds familiar. My vim always wants to indent my C headers when
they conventionally start with

#ifdef __cplusplus
extern "C" {
#endif

It's a similar case where blocks aren't really meant to be blocks.

The main question is, of course, how much does the lack of indentation
hurt? I don't notice more block structure mixups in sources where I'm
using that style, but then I'm biased. I did notice more mixups when
trying to *nest* double braces, so I'm not totally insensitive. Never
nest them, by definition double braces only apply to top level blocks.

In any case, before I release any code in this style to CPAN, I'd like
to test the waters and ask if that would, umm..., get me talked about.

Not by me anyway. I'd say that the ordinary indentation would look odder
for this case. Any reader would quickly realize that it serves no
purpose. I am pretty sure that the first thing I'd do when inspecting
the code would be left-shifting it. Therefore, not indenting these
top-level blocks is reasonable.

Besides, I think the samples you provided are extremely readable and
tidy, even when measured with the generally quite good CPAN-standards.
That's not going to get you talked about in an undesirable way. ;-)

Tassilo

 

[parv]

The main question is, of course, how much does the lack of indentation
hurt? I don't notice more block structure mixups in sources where I'm
using that style, but then I'm biased. I did notice more mixups when
trying to *nest* double braces, so I'm not totally insensitive. Never
nest them, by definition double braces only apply to top level blocks. ....
If anyone cares to take a look at some code, I have put up two examples,
a module and a test file, under

http://www.tu-berlin.de/zrz/mitarbeiter/anno4000/clpm/double_brace/Module.pm
http://www.tu-berlin.de/zrz/mitarbeiter/anno4000/clpm/double_brace/test-file

I read only Module.pm. At the first sight there is no trouble in
understanding or reading the code. But when i see '{{' or '}}' the
second or more times, a strong urge comes up to indent the text
contained within.

If the text could fit in all in one line, there is no need to, or
a question of, to indent.


- parv

 

[Tad McClellan]

Top level blocks, that is, blocks at file level, serve many useful
purposes.

In such cases, indentation comes as a nuisance. I have taken to using
double braces, '{{' and '}}' to delimit top level blocks that aren't
indented.

If it was me, I'd go with

{ # top level block

} # end top level block

That is better because you can understand what it's significance
is, even if you know no Perl at all.

OTOH, that is worse because the compiler won't tell you when you
forget to comment the corresponding close...

So to me, it looks kinda like "saving typing" of the undesirable kind.

I'm using them because the don't appear "naturally" in Perl
(or do they?) and they don't hurt (or do they?). I also hope to say
something like "Yes, this *is* a block. I'm still not indenting", but


that is perhaps hoping a bit much.

You've always impressed me as being insightful, and it's showing there.

In any case, before I release any code in this style to CPAN, I'd like
to test the waters and ask if that would, umm..., get me talked about.

In the eclectic mix of the Perl world, there are bound to be folks
on both sides, each of which might talk about you^H^H^Hit.

I don't find it particularly annoying or distressing.

_I_ wouldn't do it that way, but that probably just me.

 

[Tassilo v. Parseval]

Also sprach Tad McClellan:

If it was me, I'd go with

{ # top level block

} # end top level block

That is better because you can understand what it's significance
is, even if you know no Perl at all.

OTOH, that is worse because the compiler won't tell you when you
forget to comment the corresponding close...

At least during development stage a source filter could be used to
ensure that the markers are all there:

package TopLevel;

use Filter::Simple;

FILTER {
my $where;
my $opened = () = /\{ # top level block(?{ $where = pos })/g;
my $closed = () = /\} # end top level block/g;

my $line = substr($_, 0, $where) =~ tr/\n//;

die "Found uneven top-level blocks: ",
"$opened opened (last one around line $line), $closed closed.\n"
if $opened - $closed;
};

1;

The reported line number is a little off, though.

Tassilo

 

[Anno Siegel]

[...]

I have taken to using double braces, '{{' and '}}' to delimit top
level blocks that aren't indented.

... I'd like to test the waters ...

Thanks to all who replied, and also to those who through not replying
expressed an indifference which I am free to interpret as a lack of
outrage. (Whee... what *have* I been reading lately?) Let me reply
summarily in my own followup.

First off, no one doubted that avoiding indentation is desirable under
some circumstances. Someone (sorry, lost attribution) objected that
indentation wouldn't hurt when the lines were short enough. But the
loss of line space isn't the only reason. You can usually (without
indentation) scan down the left margin of a Perl source to find sub
definitions (and run-time actions). I want to preserve that state
through some routine situations.

Also, there were no technical objections. I mean, those double braces
actually compile an extra block (it isn't optimized away). By all
accounts that should be equivalent to a single block, but this is
Perl, after all...

No-one really loved my tentative solution (I didn't expect that), and
some expressed outright queasiness. Not to be dismissive, but that was
also to be expected. After all, it goes against ingrained indentation
habits (that took some pain to learn). But so will anything that avoids
top-level indentation; short of a source filter there will be a visible
"{" with no indentation to follow. Using "{{" doubles the offence,
but that *can* be read as "this is deliberate".

Tad suggested using a standard comment instead of doubling the braces,
and Tassilo (whom I thank for his kind words), even suggested a source
filter to balance-check them. However, the room after the opening and
closing brace(s) of a block is sometimes used for source-related comments,
I don't want to occupy the place.

Tad'd personal comment

I don't find it particularly annoying or distressing.
_I_ wouldn't do it that way, but that probably just me.

also neatly summs up the general tenor.

I'll go on with the double braces for a while. For published code there
ought to (and will) be a comment near the first occurence that explains
the praxis.

Anno