Nearly all of the ICS 22 lab assignments require that you write some Java code. In ICS 21 you concentrated mostly on the correctness and completeness of your programs, but from now on your grade will also depend on other qualities. A good program has many attributes, such as correctness, efficiency, ease of learning and use, reliability, modifiability, and clarity. Correctness is paramount, but "anything that works" is the attitude of a hacker, not a professional. A professional-quality program must score highly in all these categories, and we intend to help you learn how to write professional programs.

One aspect of professional programs is their style. When we speak of programming style, we use the term "style" not in the sense of an author's manner of expression--Hemingway's style is different from Joyce's--but in the sense of "good, clear style" that everyone should strive for. Achieving that clarity requires work at many levels, from the overall design of the program's classes, algorithms, and data structures, to the mundane details of indentation, capitalization, and spacing.

Throughout the course we will concentrate on the major design issues; in this document we focus on the smaller details. Yet these details are not cosmetic trivialities. Adhering to consistent style guidelines helps you write clearer, more modifiable, more reliable, and generally higher quality code.

The style guidelines we present here are good ones. We require that you follow them (perhaps with amendments your TA makes) for your programming in this course. That is not to say that every detail of these guidelines is superior to any other way of doing things, but for the sake of consistency we require that you follow these guidelines in this course. You will find that many organizations have coding style guidelines that all their programmers must follow.

However, nobody should follow style guidelines slavishly. If you come upon a specific situation where the rules don't make a program clearer, the rules should give way (though you should check with your TA to make sure).

Program design and organization: You should organize your program so that its structure is clear, using abstraction of various kinds to hide unnecessary detail at each level.

*   A main strength of Java is the set of features it provides to support object-oriented programming. Wherever appropriate, you should design your program in terms of the real-world objects it represents, making good use of classes and their associated operations.

*   Your classes should use the features Java provides for abstraction and information hiding, including where appropriate inheritance and private methods and instance variables.

* Methods should almost never be longer than one screenful; break long methods into sub-programs.

* Use symbolic constants wherever applicable. Other than zero and one, you should have no literal constants (i.e., no numbers) in the body of your program. Every number has a meaning, and you should capture that meaning in a constant definition. (But that doesn't mean following the silly practice of defining eponymous constants like static final int TEN = 10; --use meaningful identifier names.)

Choosing identifier names: You must choose identifier names that convey their function clearly to anyone reading your program.

* The names of void functions (and of methods whose return value is only a status indicator of successful completion) should be imperative words or phrases-- commands that describe their actions.

     public void printFormLetter (Name n, Address a) {...}

     public boolean fillRecord () {...}

     public int sortByVegetableName () {...}

* Other method names should usually be nouns, naming the value returned.

     public double insurancePremium (long ZipCode) {...}

     public numberOfFlights sizeOfFlightRecordCollection () {...}

* Names of methods that return boolean values should be declarative statements, so that they "read correctly" when they're called.

     public boolean cityNameIsValid (Response nameToCheck) {...}

     if (cityNameIsValid (usersInput)
       System.out.println("That's a city name, all right.");

Indentation and spacing: The key concept here is to include enough white space so that more closely related items appear closer together than less closely related items. This should make the program's organization apparent. Never be stingy with blank lines; use them to help guide the reader's eye to what's important.* Start each new statement and each new data definition on a new line. Break long lines at a clear, convenient place and indent the continuation to indicate that it's not a separate new statement.

Documentation: The documentation required varies from one assignment to the next, but at a minimum every assignment should have the following. Remember that comments can't make up for poorly chosen identifier names or unclear code.* Include a comment at the top of the program that includes your name, your student ID number, the course, your TA's name, and the name and number of the assignment.

* Every procedure should include a comment that describes the procedure's purpose, the kinds of parameters it expects and any assumptions about their values (this is called the procedure's precondition--what's true before it starts), the values it returns or actions its performs (its postcondition--what's true after it executes), and a high-level description of the method it uses if that method isn't obvious from reading the code.

* Explain any intricate or obscure sections of code in comments if you can't rewrite them to be less obscure.

* Because comments appear along with the code, you can assume that the reader of your comments knows how to read Java, even though he or she isn't familiar with your particular program. Thus, you should avoid silly, redundant comments like this:
total++; // Add one to the total.

Safety and reuse: Don't reinvent the wheel, at least when you have permission to use an existing wheel. In real-world software development, program designers learn and use vast libraries of classes and programs so they don't have to rebuild everything from the ground up.

In an introductory course such as this one, there will be times when we ask you to build something from the ground up because you need to learn the construction techniques involved. But when we don't tell you to build something from scratch, you should use existing code where possible and where permissible (which means, of course, that you can't use your classmates' or roommates' code--see below).

Code reuse is particularly valuable when the existing code has qualities that your code lacks, such as extra features, clearer design, or thorough error-checking.

We will use the program grading form shown below; you should read it now and use it as a guide when you write your code. Notice how large a portion of your grade depends on issues of programming style.

Turning in lab assignments: Each assignment describes what to turn in. Typically this includes both a paper copy and an electronic copy.

Place all the parts of your paper submittal into a manila envelope so that it forms one package. Make sure your name, your student ID, and your TA's name are written on the front of the envelope. Then give the envelope to your TA in section.

For electronic submission, use the Checkmate system at checkmate.ics.uci.edu.

Please refer to the course outline on the importance of keeping backups; papers do get lost, and servers do crash, and we'll expect you to be able to produce a replacement copy easily if either misfortune should occur again.

Late assignments: Assignments will typically be due at the start of your discussion section on the date specified on the assignment; your submission to Checkmate should be complete by then and your paper submission should be ready to hand in. We expect everyone to turn in by the due date whatever work they have completed; significant lateness will incur penalties. (We can make exceptions for major illness or emergency, but not for conflicts with other classes or work.) We will give partial credit for work that is partially complete but correct as far as it goes; this is another reason why you should develop your programs in stages, coding and testing and debugging as you go, rather than trying to do it all in one big push.

Early assignments: We will award a bonus of 5% for any assignment that is turned in more than 48 hours before the due date; we hope this will encourage you to begin work early on your assignments. This bonus, like all extra credit on labs, can make up for points missed on other lab assignments, but it does not "spill over" past 100% to make up for points missed on exams. The 48-hour figure is firm; please don't come asking for the bonus if you miss the cut-off, even by a short while or in circumstances beyond your control.

Academic honesty: Part of being a professional is following the profession's norms of accepted behavior. As you know, you may not copy commercial programs from the lab machines to use at home. Likewise, in an academic setting you may not turn in someone else's work as your own.Footnotes

As a general principle, we expect you to do your own independent work in all parts of this course. In this course it is always permissible, even desirable, to talk with your classmates about the conceptual course material or the requirements of an assignment (though the instructor or TA will be most reliable for this). It is always permissible to get help from anyone about using the programming environment or other system details, help with minor syntax errors, or suggestions possible test cases for your programs (though when an assignment requires it, you must write your own description of your test plan). It is never permissible (except if an assignment explicitly allows or requires working in groups) to copy another student's solution (whether code, prose, or math). A good rule of thumb is this: Any time you find yourself writing down (on paper or by electronic means) part of someone else's solution, you are copying impermissibly.

Turning in another person's work as your own violates the honesty policies of ICS and UCI (http://www.ics.uci.edu/academics/policies/icsAcademicHonestyPolicy.php, http://www.ics.uci.edu/academics/policies/uciAcademicHonestyPolicy.php). The ICS Department takes academic honesty very seriously and imposes serious penalties on students who violate its guidelines. Detected violations could result in your failing the course, having a letter filed with the school, and losing a variety of other benefits and privileges. We do check for academic dishonesty both manually and automatically. It is an unfortunate fact that nearly every quarter, some students in ICS classes are found to have violated these policies; to protect the privacy of the guilty, violations are not made public, but sadly, they do occur. No matter how much pressure you feel from deadlines or other sources, no matter how inconceivable it is to you that you might not complete an assignment on time, never take the shortcut of turning in someone else's code. Compared to the consequences of academic dishonesty, one low assignment score is a minor disadvantage. If you feel as if you're falling behind or have other difficulties, see your TA or the instructor; we are more sympathetic than you might expect.

We do encourage all students to help their classmates with the course material and the labs, within certain limits. Helping someone else doesn't hurt your grade; we don't have any limits on how many As or Bs we can give. It is even permissible in ICS 22 to let someone else look over your code to get an idea of how you organized it. However, you should not let anyone copy your code, either on paper or electronically. In fact, it is wise to keep your code in your own possession; if you give a copy to someone else, even if it's just "for reference," that person might be tempted to copy portions of your code; then you could be accused of academic dishonesty.

Most importantly, realize that getting "the answer" is only the last part of each assignment. Equally important is the process of getting the solution--including the false starts, bugs, misconceptions, and mistakes--because the learning occurs in the doing. Completely apart from the ethical issues, copying a solution deprives you of the whole point of the assignment.

Working at home: Doing your lab work at home is comfortable, convenient, economical, and safe. It also benefits students who work in the lab, by freeing up the machine you would otherwise be using. You are welcome to do your lab work at home or anywhere else you have legitimate access to a computer, but in addition to the advantages just noted, there are also some potentially serious disadvantages which we will address below, and which you must consider as you decide how best to complete your labs.

*   To ensure fairness, consistency, and efficiency in the grading, all the code you turn in must work correctly in the Java environment in our lab. If you develop your code on a different computer, operating system, or Java environment, it is entirely your responsibility to "port" your software to work in the lab by the due date. Java is supposed to be perfectly portable across platforms, but (especially if you're using Java or Java-like products from Microsoft) there still may be subtle, undocumented differences that are extremely difficult to identify and work around. You can imagine how frustrating it would be to have a program that worked fine at home crash in the lab, especially right before a due date. It will be your responsibility to avoid these frustrations to the extent you can, and to deal with them yourself, without doing damage to the lab machines or your classmates, when they arise despite your best efforts. To reiterate, porting problems will not be an excuse for late assignments.

*   For some of the lab assignments, there will be data or code that you'll need to incorporate, which we'll supply on the lab servers. You will need to copy this information from the servers onto floppies (or via the Internet) to use at home.

*   For some of the labs, we will use software other than Java, though we anticipate that any such software will be available over the Web.

*   Working at home is convenient, but it's also isolated; close friendships and a "support network" develop among students who use the labs. These are your first "professional contacts;" it would be unfortunate to close yourself off from them completely.

Grading Criteria for ICS 22 Programs

Here are some guidelines for how we will assign points for the programming portions of lab exercises. (Note that most exercises have points for others activities as well, such as test plans and prose analysis.) Your TA's criteria may vary slightly; he or she has the primary grading responsibility for your laboratory work.

Correctness for valid data. Are the answers right? Is the output spacing correct? Does the program do what it is supposed to do for any data that meets the problem's specifications (i.e., does the program handle every situation that it's supposed to handle?)	40%
Robustness in the face of unusual data. Does it crash when given no data, more than the maximum allowable, bad data values? Within the limits of the specifications, does the program bomb when it gets garbage? Instead, it should print an informative message in these situations.	10%
Quality of solution; choice of algorithm. Points deducted for particularly graceless, awkward, cumbersome, or inappropriate way of going about the problem.	10%
Design quality. Is the program divided into logical parts using classes where appropriate, each encapsulating a single task and using abstraction techniques where applicable, or are the statements for a given task scattered all over the program or run together with other tasks?	10%
Identifiers. Were the identifier names and symbolic constants chosen to reflect their function? Are they meaningful to the reader, or do they require a lot of explanation?	5%
Format of source program. Does the program follow the course's style conventions? Is white space used well?	5%
Documentation: Are there enough comments to make the program clear to the reader (noting that good modularity and identifiers make the commenting burden lighter)? Are any unusual portions of the code explained? Do the comments clutter up or interfere with the program text? Does the external written documentation, if required, give the reader a lucid overview of the program's organization?	20%
TOTAL	100%

Written by David G. Kay (1990), including much material adapted with permission from Appendix E of Programming for People/Pascal by David G. Kay (Mayfield, 1985).

Revisions made to reflect THINK Pascal by Joe Hummel and Norman Jacobson, January, 1992.

Minor revisions by Norman Jacobson & Theresa Millette, December 1992.

Prose polished by David G. Kay, January 1995.

Revised for C++ and object-oriented programming by David G. Kay, with assistance from Rasheed Baqai, January 1997.

Revised January 1998 and September 1998 by David G. Kay.

Revised yet again by David G. Kay, April 1999, particularly to address honesty and professionalism.

Revised January 2000 to reflect Java by David G. Kay, and revised further in January 2001 and January 2003.

Friday, January 10, 2003 -- 6:18 PM