-------------------------
Week 08 Notes for CST8165
-------------------------
-Ian! D. Allen - idallen@idallen.ca

Remember - knowing how to find out an answer is more important than
memorizing the answer.  Learn to fish!  RTFM!  (Read The Fine Manual)

-------------------
INDEX to this file:
 - notes on the current assignment:
   SMTP client in Perl using Net::Telnet
   Automated Testing
-------------------

This week, I went through the template file smtpclient_v1.pl.txt in detail.

The symbol XXX flags things that need fixing, adjusting, or removing.

Comments labelled "Perl:" are teacher comments explaining how Perl
works to students learning the language.  The "Perl:" comments would
never appear as comments in a production Perl program, since they have
nothing to do with how the program works.  Don't write comments like
these in your submitted Perl programs.

Comments in your code must explain why the program is doing what it is
doing, and what is happening in the overall algorithm.  Comments will
not explain how the language works; unless, your use of the language is
complex or tricky and requires explanation!

For full marks, remove all the XXX and "Perl:" comments from the template
file before you submit it!

Topics covered this week:
 - conversion between Unix LF and Internet CR+LF
 - mandatory use of the exit codes (documented in <sysexits.h>)
   - programs that send email need to signal to other programs whether
     or not they worked
   - if the program failed, was the failure permanent or temporary?
 - use of Perl: warn(), die(), join(), push(), split(), undef
 - use of Perl: arrays, $#arrayname, @arrayname
 - use of Perl: regular expressions
 - commenting style
 - no "magic numbers"
 - no duplicated code
 - make your programs easy to maintain and update

Q:  T/F In Perl, warn() prints a message on standard error and exits
    the program with a good (zero) return code.

Q:  Why must a client program that sends email return one of the
    values documented in sysexits.h?

Q:  Explain the two broad categories of errors documented in sysexits.h
    - what is the major feature that distinguishes the two types?

Q:  T/F In sysexits.h, we see many numbers indicating permanent failure
    codes; but, only a single number for a temporary failure code.

Some people found and used a Perl module that will parse command line
options.

Automated Testing
-----------------

Some forms of programming have you write the test suite first, then
write the code to pass all the tests.

I've provided a script that will do automated testing of your SMTP client,
and I've written a few automated tests.  You must add your own tests.

You must understand, by reading RFC2821, the responses that an SMTP
server might issue when you write your test cases.

If you start immediately using the automated testing script to test your
client, you'll save time over doing manual testing and then having to
repeat all your tests for the test suite.

Error Messages
--------------

Error messages in this course must have four characteristics.
See note file "programming_style.txt".