Precisely. As I've stated elsewhere, this is an internal helper
function, to be called only a few times under very well-specified
conditions. The assert statements checks that these conditions
are as intended. I.e. they are checks against the module writer's
programming errors.
This implies that somewhere in said module you must be doing
validation of "end user" inputs -- but you've not shown that; you've
just presented a raw snippet of code, whether internal or not, which has
a strong smell of validating "end user" input data via assertions.
Furthermore, if this is supposed to be part of a module supplied to
students to assist in some exercise... why the concern for clarity vs
reuse... It would be a black box to the students; they invoke your
primary function and get some result back... OTOH; if the intent is for
them to study the module code as supplied, wouldn't it have been prudent
to supply "us" the entire module too?
From your initial post:
I'm will be teaching a programming class to novices,
Do you really want to inflict novices with the subtleties of when
"assert" is a proper structure to use? At least, not without giving
examples of what it applies to... You state the function is an internal
utility to the module -- does the module then include both a flawed main
function and a correct main function? By this, I mean something like one
version of the main entry point which DOES do validation of end-user
input, and a second version which skips the end-user input validation --
both then calling this utility function. Explain that the assertions are
part of a specification for the utility which states that end-user input
"... has been validated prior to calling ... " the utility. And then
demonstrate by running the same set of good and not-good inputs through
both versions of the main entry point? (Now you are getting down to
requirements specification and/or use case documentation... again
something rather over the head for novices, no?)
Are you teaching "intro to programming in Python" or "intro to
software analysis and design" (the latter, in my view, should be
language neutral, and heavy on documentation of what components are
responsible for which actions and maybe even how to perform them). Even
the convention of the "_" for "internal/private use" is something you'd
have to explain to them. Novice programmers will likely have enough
problems with the evaluation of boolean conditionals in "if" and "while"
statements, looping, and how "x = x + 1" is NOT an algebraic
impossibility (while at the same time "x = x * 1" is algebraic
truth){even accounting for the fact that in Python, the algebraic
versions would be written with "=="}
Dumping an undocumented utility function on novices for study is not
my idea of a learning experience... As a final exam, maybe...
--
Wulfraed Dennis Lee Bieber KD6MOG
(e-mail address removed) (e-mail address removed)
HTTP://wlfraed.home.netcom.com/
(Bestiaria Support Staff: (e-mail address removed))
HTTP://www.bestiaria.com/