http://www.perlmonks.org?node_id=418220


in reply to Perl Babysteps 1: Your First Simple Script

  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # 
  # hello.pl
  #  Displays a warm greeting.
  #  
  # AUTHOR
  #  Brian Wisti (or webfiend on perlmonks)
  # DATE
  #  28 December 2004
  # VERSION
  #  1.0
  # PURPOSE
  #  Demonstration script for my Perl tutorial
  # USAGE
  #  perl hello.pl
  # LICENSE
  #  You may copy and redistribute this program as you see fit, with n
+o
  #  restrictions.
  # WARRANTY
  #  This program comes with NO warranty, real or implied.
  # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #

[download]

You meant 

=head1 NAME

hello.pl - Displays a warm greeting.

=head1 USAGE

    perl hello.pl

=head1 DESCRIPTION

Demonstration script for my Perl tutorial

=head1 LICENSE

You may copy and redistribute this program as you see fit, with no res
+trictions.

=head1 WARRANTY

This program comes with NO warranty, real or implied.

=head1 AUTHOR

Brian Wisti (or webfiend on perlmonks)

[download]
and the version in the package global $VERSION, I hope.

Don't document in comments. See also POD in 5 minutes. It's not scary.

Juerd # { site => 'juerd.nl', plp_site => 'plp.juerd.nl', do_not_use => 'spamtrap' }

Replies are listed 'Best First'.
Re^2: Perl Babysteps 1: Your First Simple Script
by Mr. Muskrat (Canon) on Dec 30, 2004 at 16:40 UTC

    And it's easier to teach one thing early on and expand that knowledge later. If you teach to much, they will not retain the information.

    For example, on day one you show them comments.

    "Comments begin with the hash (or octothorpe) character."

    # I am a comment!

    [download]

    And leave the POD for a later day...

    "Today we will learn about POD. POD is short for Plain Old Documentation and it is a fairly simple way of documenting your code. We'll begin by adding a heading to your existing project and then cut back to the code."

    package Beginner::Project;
use strict;
use warnings;

# may or may not be lots of code here

=head1 NAME

Beginner::Project - a project worthy of a beginner Perl programmer

=cut

# your code continues here...

1;

    [download]
[reply]
[d/l]
[select]
Re^2: Perl Babysteps 1: Your First Simple Script
by webfiend (Vicar) on Dec 30, 2004 at 19:16 UTC

    It's scary for the people I'm writing to :-) Tutorials like these are for my dad or brother, who have never fiddled with another programming language for more than a few minutes. The script header bit is just getting them into the habit of documenting in the first place. I agree that once they're ready for POD, they should switch over. But as it is, I'd have to explain POD, formatting, perldoc, and package global variables (which means I'd have to at least glance at packages and scoping).

[reply]
    A reply falls below the community's threshold of quality. You may see it by logging in.

In Section Tutorials