> If you made this clear somewhere else in the syllabus or homework
> documentation then forgive me for the redundant question... but are
> there any specifications that we have to follow when it comes to
> whitespace, comment style, bracing style, and/or variable and member
> variable names?
>
> Sun has conventions for many of these areas, but not for
> others (or they are conventions at sun, but not at other
> places). Please advise.
[More than you may want to know about the subject]
The TFs may have more to say about this topic. Rich has
already made a few comments about my notes for day 1
("Capitalize names of Classes, but not names of methods
or fields.") He may have comments for you as well.
My first rule is "to thine own self be true". You should
develop a clear coding style, and you should review various
alternatives on a regular basis. While many of us have
strong feelings about style, what we look for first is
organization and consistency. I can even take those
hideous emacs-style braces indented two spaces - as
long as everything lines up. When I have to work on code
that is messy and unorganized, I tend to think the author
is lazy and disorganized, I get a headache, and I think
about taking out a contract on the author. This extends
to "clever" programming and poor choice of names.
I will sometimes modify my style, which is quite generous
with white space, when printing a handout or making overhead
slides, where space is precious. Rules are not absolute.
Some good starting points are
The Elements of Style - E.B.White. At the Coop.
The Indian Hills C style guide - off the "Interesting Stuff" page
The Sun Style Guide - Also off "Interesting Stuff/Style Guides"
http://harvard.altisimo.com/cscie119/useful-stuff.html
I often have the luxury of being able to talk you through a
Class or method. Often my code will have fewer comments than
you might like, and fewer than the TFs might like.
As times goes on, you will gain a feel for some common idioms.
When you stick with well understood forms, comments may get
in the way.
i++; // Add one to i
You may find that comments that were too brief
at the start of the course seem verbose at the end.
For what we are doing, I think the Sun style of Javadoc
comments (see WarmUp.java) is overkill, but it is very
useful in a large project that will have a long life time.
http://harvard.altisimo.com/cscie119/homework/hw0/WarmUp.java
While I read the comments, I believe the code. Few people
file bugs on comments, and many a bug is fixed without
updating the associated comment.
- jeff parker
