Coding Style
Just like human languages, programming languages have a particular
syntax and grammar. If you make a mistake, you end up with a program
that is invalid, or "gibberish." And just as publishers and
periodicals have "house styles" that govern how to indent paragraphs,
how many spaces to put after a period, which abbreviations to use or
avoid, etc., companies and programming projects also adopt style
guidelines.
imaginereadingatextwherenothingwascapitalized,therewasno
spacebetweenwordsandaroundpunctuationmarks,andparagraphswere
separatedbyonlyatinyblankspace.thetextwouldpreserveits
meaning,butbenearlyimpossibletoread. Furthermore, if every article
(or every paragraph) in a magazine adhered to a completely different
style, it would be almost as confusing. Programming is no different,
except that it is far easier to make a syntactically correct program
unreadable by using poor or inconsistent style. Good style is
essential to programming, and a substantial portion of your homework
grade will be based on style.
Programming style generally encompasses how you indent your code,
when you put spaces around operators, and how you name variables,
functions, and classes. There are many opinions about what
constitutes the best style, and most companies and projects adopt
their own guidelines to ensure consistency. In CIS 110, we follow
the textbook's
style guidelines. These are typical of the rules you are
likely to encounter elsewhere, but represent a particular set of
choice among many possibilities. Here are some of the highlights:
- Indentation
- Each block of code must be indented 4 spaces to the
right of its parent block. A block is any section of code
enclosed between curly braces ({}). If you use the introcs
installer to set up Dr. Java as part of Homework 0, it will be
configured this way automatically. You can re-indent the
current line by pressing TAB. You can reindent a whole
section by selecting it and pressing TAB. You can reindent
the entire file by selecting everything (Cmd-A on Mac, Ctrl-A
on Windows), then hitting TAB. Do not indent your code
manually with spaces, let Dr. Java do it.
- There is no excuse for improperly indented
code. Ever. Whenever you start
typing a new line of code, press TAB to make sure your cursor
is in the right place. Whenever you cut and paste, or insert
code, select the region around it and press TAB to reindent.
Badly indented code is impossible for humans to read, and
impossible to debug. If Dr. Java automatically indents
your code in a way you don't expect, you have a bug.
Usually you are missing a semi-colon or curly brace.
- If your code is not properly indented in office hours, we
may refuse to help you. There is no rule that is more
universally agreed upon than the importance of correct
indentation. There is also no single, simple thing you can do
that will help you more than correctly indenting your
code.
Variable and Class Names
- Variable names and function/method names start with
a lower-case letter. If the name is a composite of
multiple words, each subsequent word starts with a capital
letter. For example, "var" is an acceptable
name for a variable, and
"thisIsAVariableName" is also an acceptable
name for a variable. The names
"ThisNameBeginsWithACapitalLetter" and
"this_name_contains_underscores" are not
acceptable for variables in CIS 110.
- The same rules apply to functions
and methods (we introduce functions and methods in
the course of the semester). The first convention, that
variable names begin with a lower-case letter, is very
widely accepted. On the other hand, many projects and
companies prefer to separate words with underscores ("_")
rather than using capital letters.
- As an exception to the above rule, constant variable
names should be all upper-case. Constant variables are
variables whose value never changes. Alternatively, think
of these as symbolic names for particular values. The
canonical example is a variable whose value is 3.14159...
This variable would be named "PI" rather
than "pi". This convention is also widely
accepted.
- Class names should begin with a capital letter. If
the name is made up of multiple words, each word should
begin with a capital letter. Once again, this is a widely
accepted convention in object-oriented languages. It is
often difficult to tell from context whether a name refers
to a variable or a class. By following the capitalization
conventions your code becomes much easier to read and
understand.
Spacing
- Use a single space on either side of mathematical
operators (+, -, *, /). For example, write
"x + y", not "x+y".
- Put a space before an opening curly brace, or else put the
brace on its own line. Be consistent in your choice.
Put the close curly brace on its own line.
- Do not put a space before the square brackets for an
array. For example, write
"String[] args" and
"args[0]", not
"String [] args" or
"args [0]".
- The spacing around parentheses corresponds to how you would use
them in English and math:
- Put spaces outside the parentheses, but not inside
them, when they are used to group mathematical
computations. For example, write "a + (b +
c)", not "a +(b + c)"
or
"a + ( b + c )".
- Put spaces outside the parentheses, but not inside
them, when they are part of a loop or conditional
(if, for, or while). For
example, write
"if (x > 5) {", not
"if(x > 5){" or
"if ( x > 5 ) {".
- Do not put spaces around parentheses when they are
part of a function call. For example, write
"System.out.println("hello, world.")",
not
"System.out.println ("Hello, world.")"
or "System.out.println( "Hello, world."
)".
We use the checkstyle program to automatically detect
many (but not all) violations of the textbook's style
guidelines. On most assignments, you will see the output of
checkstyle when you submit the program. If there are any warnings
that we have not specifically told you to ignore, you should
correct them and resubmit or risk a style deduction. Once we
cover the terminal/command prompt, we will show you how to run
checkstyle yourself, before submitting.
Class Message Board
We use Piazza as our message board system. Piazza is a web
service specifically designed for students to post questions about the
course and have them answered by the class staff or their peers. We
also make course-wide announcements through Piazza, so make sure
to sign up for it as part of Assignment 0.
- Announcements
- Announcements will normally be made via Piazza
as Instructor Notes, and e-mailed to all registered
user.
- Instructor notes will be e-mailed from
"CIS 110 on Piazza", and the subject will
start
with [Instr Note]
- You are responsible for the content of all announcements
on piazza.
- Announcements will normally also be pinned at the top of the
piazza message list until they are no longer relevant.
What to Post
- All questions about course material and assignments
should be posted to Piazza rather than e-mailed to your TA or
the instructor.
- Other students invariably have the same questions as you do,
and posting them to Piazza encourages discussion amongst
you.
- If you e-mail a question directly to a TA or the
instructor, you will likely be asked to repost it to
Piazza.
- We encourage you to post questions publicly as much as
possible (you can set your posts to be anonymous to your
classmates), and to answer each others' public
posts.
- Answering questions on Piazza is a great way to learn yourself,
and we take it into consideration when grading.
Finally, don't forget to search the message board before
posting. If you haven't searched yet, there is a high
probably your post is a duplicate (even if it is about an error
in your code).
When to Post Code
- The best way to get programming help is in person, in
office hours. However, this is not always possible, and
sometimes we need to look at your code in more detail to find
the problem, then get back to you.
- You may post private questions to Piazza that
include your code when necessary. To do this select Post To
"Instructor(s)" rather than "Entire Class" at the top of the
posting form. Private posts are visible to all TAs and
instructors, but not other students, so it is safe to post
your code this way.
How to Post Code And Error Messages
We need to be able
to read the code, and have enough information to help you debug
it, so it is import to follow these
guidelines when posting code and code-related
questions:
- Do not e-mail code problems to your TA or the instructor
unless you are specifically asked to. Post to Piazza
instead. We will be able to answer you better and faster that
way.
- Cut and paste the specific compiler error, or the specific
test your ran and its output into your message. These error
messages may well be cryptic to you, especially early in the
course, but they are very specific as to the problem. We will
help you understand what they mean, and how to use them to
diagnose and solve your problem.
- Enclose the output you cut and paste between
"<pre>" tags like in the example below. There
is no special button to enter <pre> tags in
Piazza, you simply type them in like ordinary text.
<pre>
HW.java:24: class HelloWorld is public, should be declared in a file named HelloWorld.java
public class HelloWorld {
^
1 error
</pre>
- The <pre> tags ensure the output is formatted exactly
like in Dr. Java or the Terminal/Command Prompt. Without
them, the web browser reformats the text and makes it harder
for us (and you) to read.
- We usually prefer public posts that include the exact
error and a description of how it occurred. That way all
students can benefit from the question and answer. If we
can't answer your questions, we will ask you to either come to
office hours or post a private question with your code.
- Post your code between <pre>
tags. If you don't put it between <pre>
tags, all indentation will be lost, and we won't be able to
read it. This is the most annoying thing about Piazza, and
therefore the most important thing for you to
remember.
- INDENT YOUR CODE CORRECTLY!
In past semesters, we have received numerous posts with
un-indented code (even when we add the <pre> tags).
There is no excuse for this, and we can't help you if we can't
read your code.
- Post all your code. Without all your code, we cannot
reconstruct the precise situation that caused your error.
Bugs are often not where they appear to be, and we can't
always help you find the problem if you only post part of your
code. Later assignments often consist of several
files; post the contents of every file you have worked
on.
- If your post does not contain all the correct information,
is not properly indented, or does not have the <pre>
tags, click the Edit button and fix it.
You can access the message board through this link.
TA Office Hours
We offer extensive office hours in the Moore computer labs, and try
hard to have as many TAs and mentors on staff as possible to keep
wait time short. For Spring 2013, we are greatly increasing the
staff to shorten wait times.
The schedule of who has office when is
maintained as a Google calendar. We try to update this for
last-minute changes, and University holidays, but be alert to piazza
announcements of changes as well.
- Structure of Office Hours
- If you need help, add your name to the list on the board.
We help students in order.
- At busy times, we may keep several lists for different
categories of problems (e.g. different stages of the
assignment). This lets TAs and mentors "specialize" in
particular assignment areas and help students with the same
problem in small groups.
- Out of fairness to your fellow students, you may only
have your name on the board once at any given time. If
you have your name on the board more than once at any given
time, we will erase all but the last occurrence.
- Office hours for assignments end at the deadline, not
the end of the grace period! On busy days, we will close
the help list 30 minutes before the end of office
hours.
- Debugging is unpredictable and doesn't work well in
marathon sessions. Start early and start asking questions
early, and you'll make steady progress. If you come into
office hours with questions about the beginning of the
assignment the day before it is due, you should expect not to
finish it on time.
- Getting Help in Office Hours
- We welcome questions about both course material and
homework during office hours.
- We have a structured process for helping with programming
that is designed to be efficient and to help you become
independent. Depending on the stage you are in, we will
help you in one of three ways:
- If your code is not correctly
indented, we will tell you to
indent your code and move on to the next
student (see the style
section). Correctly indenting code is akin to
insisting you correctly capitalize your sentences before
we help you with your spelling and grammar. Your code
should be correctly indented at all times.
- Assuming your code is correctly indented, we will
help you understand compiler error messages so you can
get your code compiling. You
should compile your code every time you write a new
piece (even if it is only two or three
lines), and correct and compile errors before
continuing. This is analogous to thoroughly checking
spelling and grammar every time you finish writing a
sentence. It seems pedantic, but turns out to be far
more effective than writing lots of code, then trying to
compile it.
- If your code compiles, we will
ask you what happens when you run it. We'll
help you work out the best way to test the program and
interpret the results that you're seeing. This is the
heart of the debugging process, and often the heart of
understanding the assignment.
- We cannot promise that your program is correct in
office hours. That is determined during grading. You
should always reread the assignment carefully when you're
done to make sure your program does precisely what is asked.
- It may seem helpful to explain to us what you're
trying to do, but it usually isn't. Dealing with
compile errors in order, then methodically testing, is
invariably faster and leads to better comprehension.
Remember that computers blindly carry out the instructions
they're given in order, without looking ahead; as a result,
you can't properly test and debug later steps until the
earlier steps are working.
Debugging Advice
- You may wish to copy skeleton code from the assignment
into your program. If you do, make sure it is either
commented out, or compiles. You cannot debug and test
the parts that you are working on if you have included
other code that doesn't compile.
- Similarly, you may wish to "work ahead" on later
sections of the assignment while waiting for help. Even
if you do so in a separate file, your code should be
correctly indented and should compile. Otherwise the
code you write will almost certainly turn out to be
useless.
- Don't try to understand the entire
assignment all at once. Focus on one step at a
time. When you get that working, you will find the next
step much easier to understand. The expressive power of
programming comes from breaking complex problems into
manageable pieces. Most programs are too complex to
understand as a whole, and solve problems that are too
hard to understand as a whole. This is true even of most
programs that are written by a single person!
Tutoring
Tutoring is available at no charge through
the tutoring center.
In addition to private tutoring, the tutoring center offers drop-in
satellite hours and a weekly review session. See the course schedule
page for the times.
Tutoring is intended to help you understand core concepts that you
are struggling with; it is not a substitute for lecture, recitation,
or office hours. In particular, tutors are not TAs and are not
allowed to help you debug your programming assignments.
They can help you understand the concepts behing the homeworks
by working through related exercises with you. When you start working
with a tutor, you will set specific goals for what you hope to achieve
in tutoring, and that will guide your session.