This document provides information and guidelines regarding
the preparation, submission, marking and return of programming
submissions, both for the students who must prepare and submit them,
and for any marker who must evaluate them. Everyone involved with the
course is expected to be familiar with the contents of this
document.
Submission Guidelines (directed at students, but also for
markers)
Each submission involving programming will be marked for "style" as
well as "substance":
- style
- How good does it "look and feel"? In other words: Would the
program be readable and understandable when another programmer looked
at the source code, and would a user regard the program as having a
pleasant "user interface" and being generally "user-friendly" when it
runs?
- substance
- How well does it work? In other words: Does it give the required,
correct results in the proper form? Of course, the real "substance"
question for any program is this: Does the program satisfy its
original specifications and work correctly for all valid input
values, including the supplied data (if any), and does it perform any
required error handling properly?
Student responsibilities for preparing MINT-condition
submissions
Every student must recognize that it is his or her responsibility to
prepare each programming submission according to the problem
specifications, the specific instructions for that submission, and our
general guidelines, and to submit it on time in the manner specified.
Submissions to be marked will normally be made via the web, but this
may vary from time to time. MINT is an easily-remembered
acronym to help you remember what must be true about any submission
before you submit it. You must make sure that each submission is in
MINT condition, by which we mean:
- M In the opinion of the
M arker, your submission must meet a
M inimal standard of functionality, style
and overall organization. In particular, if it does not compile, link
and run, so that you can provide an appropriate executable, or if the
marker can't make sense of your source code, major penalties will
apply.
- I Every submission must be
I dentified properly, according to the
current requirements as specified by the course instructor. If it
isn't, penalties will apply.
- N All files submitted must be
N amed as required in the submission
description. If they aren't, one or more of them may be missed by
any processing software that deals with the submission, including the
brain of the marker. No file missed for this reason will be accepted
after the fact. Care must be taken to ensure that a source code file
is not submitted as an executable, or vice versa.
- T Each submission must be made on
T ime. If it isn't, it's
unacceptable.
The need to follow instructions carefully when performing any kind
of programming activity cannot be overemphasized. There are general
rules to follow for all submissions, and sometimes particular rules
apply only to the current submission. These current-submission rules,
if present, may either override, or simply augment the general rules
(another example of "local taking precedence over global", if you
like). Local rules for a given submission (if any) will appear in the
specifications for that submission.
Study very carefully the following general guidelines for program
development. Note in particular the need to properly identify both
program source code and program executables.
- Get started early, work steadily, submit frequently, and
plan to make the final submission at least five minutes before the
deadline.
Does this need any further comment?
- Look before you leap into program development.
Read completely through the entire description before starting to
work on any required submission. This will help ensure that you
follow any explicit instructions that apply only to that particular
submission, and that you don't waste time doing things that
you shouldn't be doing for that particular submission. If
specific instructions for a particular aspect of a problem are not
given, you may exercise your own judgment as to how that part of the
work should be done, but you will be expected to conform, within
reason, to the general approach to program development discussed in
class and illustrated in the relevant examples seen in class and in
lab.
- Follow the required programming (coding) style guidelines.
These style guidelines will not be repeated here, since they are
covered on a separate page.
- Test any program carefully before submitting it for
evaluation.
Always use the exact data supplied (if any) or the kind of data
suggested (if any) to test the version of your program that you
intend to submit, although you will of course often want to (or have
to) use additional, or other, test data in the process of developing
your program. Markers may use a standard set of test data to test
your program, and it may be test data that you have not seen.
-
Identify your source code and executable properly.
- Identification of source code
All source code files submitted must be identified by including
at the beginning of the file one or more comments having the form
specified elsewhere by the course instructor.
- Identification of executables
When a program runs, it must also identify itself and/or the
programmer who created it, and possibly provide some additional
information, using the format and having the content specified
elsewhere by the instructor.
- Your program must provide any required descriptive text
and/or on-line help
Whatever additional information the program must display when it
runs, if any--such as on-line help or a more elaborate description of
its purpose and usage--will be described as part of the description
of the requirements for each particular submission, or will be shown
by the sample executable, if any.
Markers, as well as students, should keep in mind that any submitted
program must be complete, correct and understandable, if full marks are
to be awarded. In other words, not only "substance" but also "style" is
important in the construction of a computer program. Another thing to
keep in mind is that there are always two major aspects of a computer
program to consider when evaluating that program: first, the source
code; and second, the output from the executable code when it runs.
From time to time students may also be required to submit additional
material relevant to a submitted program, design documentation of some
kind, or a help file. For more complex programs than we will be
writing, a User Guide and additional "external" documentation would be
necessary, and would have their own requirements.
The question of just how a submitted program should be evaluated is
always a thorny one. For full credit the student's solution must, of
course, conform in all details to the particular specifications of the
given submission as well as the general guidelines contained herein. To
make a full assessment of the submission the marker may need to
consider, and will certainly find helpful, the student's own assessment
of that submission, so students must not forget to include their
assessments in their submissions. Your self-assessment of your
submission should appear in a brief comment after the blank line
following the required comments at the beginning of your file. It may
simply say that you consider your submission to be complete and working
as required, or outline briefly whatever problems you were unable to
resolve.
When a marker begins to evaluate a student's submission, he or she
expects to see something that has been produced in accordance with the
general guidelines set out herein, as well as the specifications set
out in the description of the given submission. It should work
correctly and have a good "user interface" when it runs. And the source
code should be understandable, i.e., the marker should be able to see,
without difficulty, by looking at the source code, that the program
does work correctly, as well as how and why it works correctly and does
what it does.
If this is the case, the student can expect, and the marker
should allot, full marks. If this is not the case, the student
can expect to have marks deducted, and markers are obliged to deduct
marks.
The difficult question is always this one: How many marks should be
deducted for which omissions or which transgressions? One problem is
that questions of style do not have right and wrong answers. But that
is why we have gone to some trouble to make our style expectations
explicit, and students should realize that if they continue to ignore
these guidelines, they do so at their own peril. And it is worth
pointing out as well that these are not arbitrary guidelines. For the
most part, they are the condensed wisdom of several decades of
programming experience in North America and elsewhere, and grew out of
the hard lesson that when programmers program without such guidelines,
sooner or later chaos reigns.
Consistency is a very important criterion in marking, but one that
is almost impossible to achieve in the full sense of the word. All we
can reasonably expect is that markers will do their best.
Finally, we point out that if a marker observes a particular student
continuing to violate a particular guideline after being warned, that
marker is free to increase the amount of any previous point deduction
for that particular infraction.
Evaluation of program readability (i.e., program source
code)
When evaluating the source code of a program, items to be considered
will include, but need not be limited to, the following:
- Identification
- Has the program been properly identified, according to the
standard method of identification established for the course?
- Formatting (spacing, indentation, alignment, grouping)
- Is the horizontal and vertical spacing adequate for good
readability?
- By horizontal spacing we mean blank spaces, since TAB
characters should never appear in source code.
- By vertical spacing we mean blank lines and/or page breaks.
Are indentation and alignment used properly and consistently?
Are logically distinct sections of code separated appropriately?
- Self-documentation
- Are there enough, too many, too few, inappropriate, or no
comments?
Do all functions have appropriate pre-conditions and
post-conditions?
Does each function parameter have an in, an out,
or an inout comment?
Are the identifiers meaningful?
Does every void function name start with a verb?
Have named constants been used where appropriate?
Is capitalization ("camel-style", in general) used properly and
consistently?
- Program structure and overall organization
- Is the program properly structured?
Is the logical flow of the program clear from its structure?
Is each class properly structured?
Evaluation of user interface and executable
output
When evaluating the output when a program is executed, items to be
considered will include, but need not be limited to, the following:
- Identification
- Does the program identify both itself and the programmer properly
in the output, if and as required?
- Self-description
- Does the program describe itself properly in the output, if and
as required?
- On-line help
- Does the program provide on-line help, if and as required?
- Prompting for input
- Does the program prompt the user properly for all required input?
Does the program make all options clear to the user?
- Echoing of input in the output
- Does the program echo, in the output, any input that would enable
the user to verify that the program had received the correct input
values, if and as required?
- Organization of output
- Are items in the output grouped logically and separated
appropriately?
Is the order of items in the output appropriate/correct?
- Formatting of output
- Is the horizontal and vertical spacing adequate for good
readability?
Are indentation and alignment used properly and consistently?
- Correctness of output
- Does the program work correctly and produce the correct output?
Has the supplied data (if any) been used?
General evaluation considerations
- Have all specifications peculiar to the given problem been
followed?
- Are grammar, spelling, phrasing and punctuation correct and
appropriate?
- Have any unauthorized global variables been used?
Is the submission simply unacceptable, or subject to
particular penalties, for any reason?
- M Does it fail to meet a minimal
standard of functionality, readability, and/or organization?
- I Is is not identified
properly?
- N Are the file names
incorrect?
- T Is it late?
Marker responsibilities
Each marker will regard it as his or her responsibility:
- To become familiar with the marking guidelines outlined herein,
as well as the coding style guidelines for the course
- To read each required submission's description to become familiar
with it and any additional particular specifications it may contain,
before beginning to mark that submission
- To print, if and as required for marking, either hard copies of
student submissions, or marking sheets, as well as any additional
relevant files supplied by the instructor for reference
- To run and evaluate any submitted executables, as required, and
complete any relevant marking templates (if applicable)
- To mark all submissions according to the general guidelines set
out herein, any special instructions that may apply to a particular
submission, and/or any additional or alternate instructions supplied
by the instructor
- To place on each returned submission hard copy (or marking sheet)
a final mark out of the possible maximum for that submission. This
mark should represent a fair assessment (as a percentage) of how well
the student has completed the submission according to the guidelines
and instructions.
- To indicate (briefly) on each returned paper the reason(s) for
any lost marks, in order to provide feedback to the student by
pointing out where things have gone wrong, if they have
- To return any marked submission (or marking sheet, as
appropriate) to the appropriate return shelf (or other specified
location) or to the instructor, as appropriate, in time for those
papers to be retrieved by the students no later than one week
following their due date, and to notify both the instructor and all
affected students by e-mail if for some unforeseen reason there is to
be any appreciable delay in the return time
- To record the mark for each submission for each student in
whatever form and in whatever place has been decided at the beginning
of the term, and to retain as backup his or her own private list of
marks for each student
- To respond, within a reasonable time period, to any student
e-mail queries concerning the marking of a submission (In this
regard, markers should be aware that students know that if there is a
problem with the mark on a particular submission, they can contact
the marker by e-mail to explain the difficulty and ask for a re-mark
of the assignment or a particular part of it.
- To be able, and to be prepared, to defend any deduction of marks
with an argument based on the guidelines contained herein
- To report, to the instructor, with details, any suspected
instances of plagiarism
Due times for submissions
All submissions are due no later than 23:59:59 on the due date
indicated on the submission description page.
Late submissions
Late submissions will not be accepted. Do not send e-mail or other
messages requesting extensions, as they will simply be ignored. And
under no circumstances are submissions (late or otherwise) to be
e-mailed to your instructor or your marker. We have submission
procedures that do not involve e-email.
Each of your marked submissions, or an evaluation sheet
corresponding to your submission, will be returned to you as soon as
possible in a class or recitation following the return of the
evaluations to the instructor.
Marks will be recorded on-line and made available from a link on
the course web site. Only you (and the instructor and marker(s),
of course) will have access to your individual marks, though mark
summaries of one kind or another for the class as a whole may (and
likely will) also be available in the same location.
If you disagree with the mark you have received on a submission,
send an e-mail message to the marker, quoting whatever relevant
comments the marker has returned to you. The marker will reconsider the
submission in the light of your request, and get back to you when a
decision has been made.