Rumor
has it that grading for the project will be roughly:
50%
functionality (I.e. ‘Does
your project work?’)
50%
style (I.e. ‘Does your project look good?’)
Thus it is very important that you get your project
looking good. Here are some stylistic things that we will definitely be
checking for. This list may not be complete, but I’ll try to update you as I
know more.
¨
Commenting is good.
o
Every
function that you touch should have adequate commenting regarding its
specification. This includes the domain of the function, the range of the
function, side effects of the function (if any), values specifically prohibited
(if any), error conditions (if any), and lastly, a brief explanation of what it
does (if that isn’t obvious from the function’s name, domain and range.
o
In
addition, you should comment any section of your code that may prove confusing
to your partner or your reader. A general rule of thumb: If you think that
someone could look at your line of code and reasonably say ‘what the hell is
going on here’ (as I’ve often said to many of you), then you should put in a
comment to explain what is going on. In addition to giving you style points, if
readers can decipher what your code is trying to do, they may be more likely to
give you partial credit on pieces that don’t quite work.
¨
Abstraction is good.
o
This
will be a large part of your style grade, I think.
o
The
general rule of thumb (at least for this class) is this: Look at each of your
objects and say to yourself ‘This object is an X of Y’ (e.g. ‘list of moves’,
‘position of pieces’, etc.). You should make sure that each possible X has its
own constructors and selectors, and that you use only those constructors and
selectors when dealing with objects of type X. Thus, if you have a list of
numbers, you should use the list interface (car, cdr, etc.) and for a position
you should make up your own selectors (e.g. get-left, get-right, etc).
o
No
DAVs!! Do not fall prey to the temptation to use car or empty? on a position or
a sentence ‘just this once’. The readers will find this and you will lose
points for it. In this class, you can’t use too many layers of abstraction.
o
Remember:
Lists use cons, car, cdr, null?, list?, filter, reduce,
¨
Test cases are good.
o
This
will also be a large part of your style grade, I think.
o
You
should provide enough test cases to prove to your reader that your entire
project works on all valid input. Thus, you should be sure to test your
individual functions in isolation (to the extent possible) and your entire
project as a whole.
o
There
really is no excuse for having a project that you think works perfectly
correctly and then, when a reader asks you ‘Well, try typing in XYZ,’ your
entire project crashes – You should have caught this case with your own test
cases and fixed it when you had the chance.
¨
Ugliness is bad.
o
I’m
not sure of the extent to which this will be graded by the readers, but, in
general, you guys have enough experience to know the difference between a
‘hack’ solution and a ‘clean’ one – if I were you, I would check over my
project to make sure that there are no hack solutions. Some good indicators of
hack solutions:
§
Nested
conds that could be combined – big no-no.
§
Functions
that are over 10-12 lines – usually the result of some sort of ugly
trying-to-do-to-much-at-once solution. Try breaking up the function into
smaller pieces.
§
‘(lambda
(x) (func x))’ rather than just ‘func’ – even though I’ve fallen prey to this
also.
§
Etc.
Note: Most of these style points, like ‘abstraction’ and ‘ugliness’, will apply equally well to the code that you write on your final exam. We will be taking points off for bad style.