Why we teach bareword filehandles

There’s a debate raging in Perl 5 Porters over some updates to perlopentut. Mike Doherty sent a patch to remove the bareword filehandles, stepping into the overlapping minefields of fashionable practice and documentation authorship. That second one is beyond the scope of Learning Perl, so I’ll ignore it even though that’s almost the entire debate.

There are three reasons we teach bareword filehandles in Learning Perl: generality, immediacy, and history. Having said that, we are not choosing between barewords or filehandle references, even if we do use the references for most of the book. We’re agnostic, and we leave it to our reader to make the best choice for them. We don’t see out job to tell you how to program. We just want to explain what Perl actually lets you do.

Generality: We don’t write books for individual people. That just doesn’t work since it would take more time than any author has, even if authors did nothing but write every second of every day. For a book such as Learning Perl which sells tens of thousands of copies just in the paper version, we have many sorts of people to think about, virtually none of whom we have ever met, will ever meet, and will never give us feedback. We don’t know why you are using Perl. You could be system administrators, web programmers, data mungers, or, sometimes, non-techies. We don’t know if you are writing new code or adjusting old code. We don’t know what you need, so we don’t make judgments based on what we don’t know. If you are talking to one of us during a face-to-face class, we can ask you questions and find out more about what you need.

Perl suffers from success in vastly different areas. You can write quick one-liners or huge, enterprise systems. You might need an interactive user interface, or not. Different tasks and different domains require different practices. Instead of assuming that you are going to limit yourself to just one of those areas, we aim to make Learning Perl useful to most of those areas.

Immediacy: In a tutorial like Learning Perl, we have to start somewhere. A bad book can quickly overload a reader with several concepts at once. Our goal is to get people writing code as soon as possible, which is the fundamental goal of Perl. Larry Wall wants people to be able to program even if they don’t consider themselves programmers. He doesn’t want people to have to spend hours of research to be able to doing something useful quickly. Larry’s term for this is “baby Perl”.

There are several concepts that go into a this single line of Perl, none of which are immediately useful to someone who wants to write the sort of short program we consider in Learning Perl:

open my $fh, '<', $filename or die '...';

In their first afternoon of Perl, the new programmer has to be comfortable with my as well as the concepts around open, its modes, and its lack of punctuation. That my $fh inside a larger expression is really confusing for beginners. We don't make any judgements based on that. We just know that's the way it is. To avoid the extra sources of confusion, it's easier to reduce the problem to one with the fewest distractions:

open FILE, $filename or die '...';

Don't forget that the tutorial for open is almost 1,000 lines long. This is not a simple built-in. Once people get used to the idea of a very basic open, we can expand on that to add more to the readers knowledge and understanding. All education is a continual process of refinement and adjustment as you integrate new concepts with what you already understand.

History: Finally, no matter what we personally think about one form or the other, we can't deny that people are going to see the bareword versions. The "Modern Perl" movement would like to pretend that bareword filehandles don't exist, but they can't ignore STDOUT, STDERR, STDIN, or DATA. Perl has bareword filehandles and most people are going to write new code using bareword filehandles, indeed, even relies on those barewords, even if they subscribe to all of "Modern Perl". Putting that aside, though, people are going to see bareword filehandles in old code. Our readers need to know what those are and what they do. Programming is not just about writing code, it's about reading code. We can't hide widespread patterns because they've become unfashionable to some people.

10 thoughts on “Why we teach bareword filehandles”

  1. You have excellent points here. It’s too bad you missed the fact that Mike’s attempt to remove the bareword filehandles includes a section titled “Bareword Filehandles”.

    It’s true in technical documentation you often need to balance the needs of the reader, their experience and background, and the complexity of the example. There is however a difference between a book like Learning Perl and a online documentation. People tend to read a book linearly spending more time absorbing the context. They tend access online documentation a-linearly, dipping in quickly to answer a specific question or issue.

    One of the arguments behind the changes Mike is proposing is that often people will grab the first example that works for them … and then not go any further. The idea was not to “pretend bareword filehandles dont’ exist”, but rather to present the best possible examples first, assuming that people won’t read any further. Something that is much more likely with online documentation than with a physical book.

    1. I didn’t miss it. I just didn’t want to address that part. I think the debate is fairly stupid and tangential to the real issues. I don’t have any problem with Mike’s patch, and I’m not arguing against it. I am arguing against ignoring barewords, which is not what Mike did but what many people in the “Modern Perl” movement seemingly push for, just like the mindless devotion of the previous iteration of this, which we called Perl Best Practices.

      As I stressed, you can’t say anything about “best possible examples” until you know how people are going to use that code. Indeed, that’s my entire point. You have no idea what is best when you don’t even know the context.

      You’d be surprised how many people don’t read even Learning Perl linearly, but I’d also expect someone to read perlopentut linearly.

  2. Presumably, before reaching tutorials on opening files, a new learner will have encountered the very basics of using ‘my’ to define variables within a local scope (if not – they should have!)

    OK, using ‘my’ within the middle of an ‘open’ call may be a little confusing – why not declare a variable to hold the filehandle first, then use it?

    my $fh;
    open $fh, '<', '/some/file' or die ...;
    

    The use of 'my' to declare a variable in the local scope shouldn't be anything new (if it is, they *really* need to step back and learn the bare basics without worrying about opening files just yet), and without the 'my' in the middle of the call to 'open', it should be a little clearer, I'd hope.

    One extra unnecessary but harmless line of code, but could make proper use of open() a touch easier to learn, I think.

    Of course, a quick note could explain that declaring the var before the open call isn't actually required, but is done this way for clarity to beginners.

    Thoughts?

    1. If you do that, you now have to carry around the weight of two statements to open a file. Before the new programmer can open a file, they have to understand lexical variables because they have to use strict (now on by default), and so on. As I said, at the first pass, we remove those distractions.

  3. I should add to my previous comment that, yes, the use of bareword handles should not be hidden – yes, new users are almost certain to encounter them at some point, so should understand them – but it would make sense for them to encounter the recommended way first, if at all possible, then see the “other way” afterwards.

    1. That doesn’t really make sense when you are teaching someone. It’s much easier to start simply and refine. Consider how you’d teach someone how to shoot a rifle, drive a race car, or fly a plane. Do you teach them the way that experienced soldiers, NASCAR drivers, or pilots do it? Of course not. Why don’t we teach school kids how mathematicians do algebra, or how scientists do actual experiments? All of these things are the integration of many bits of knowledge and experience. The best learning happens when people can isolate new ideas and practice those without worrying about everything else.

    1. Indeed, three argument open is good. It has nothing to do with bareword filehandles. That’s a completely different topic. 🙂

      The bug you see there exists with the two-argument open too, and it’s a problem with print.

  4. I think the camp of “never use bareword filehandles” is the same camp as “why doesn’t Perl ‘use strict’ by default”, or very close to it. They forget that some very simple 10-line (or command-line with -e) scripts are incredibly useful, and would not gain anything by increasing the barrier to coding that strict or autovivified filehandles require.

    If your code fits in a single vi window, you don’t need the “Perl as a large-code language” tricks. Please stop demanding them.

Comments are closed.