CSc 317: Code Style Requirements

At this point in your programming careers, you should already have a decent sense of what “good style” looks like for python and Java. As a general principle for this class, when you write code, ask yourself: “Is this good code style?”. If not, you might lost point(s) for writing it in that way.

For this course, you can refer to the The Android Source Code style guidelines, as the go-to place to determine if something is OK style or not. You can take a look by going to: https://source.android.com/setup/contribute/code-style. However, that document is rather lengthy. If you have time, read through the whole thing. Some of the more important bits are outlines in this document.

Comments

You should use Javadoc-style comments for your header comments and function comments.

Every Java file should have a header comment describing it’s purpose. Your file header comments should be of the form:

/*
 * @author: Benjamin Dicken
 * @description: A description of what your program does
 *               ...
 */

Also, every method should have a Javadoc style comment, which describes the functionality, parameters, and return values. The comment should describe the task that the function performs. It should also describe the type and purpose of each parameter and/or return value.

/**
 * This function does something.
 * It accepts two integer paremters, and does not return anything.
 */
public void doSomething(int a, int b) {

}

You should also put inline comments with // for any complex chunks of code within a method.

Naming

Variables and methods should always be names using camelCase. Class names should always be named using CamelCase. Constants (for instance, a public static final value) Should use ALL_UPPER_CASE_NAMES. Poor variable names may result in a penalty.

General/Misc Code Structure

You should do your best to submit code that is well-structured and easy-to-read. Some guidance for this:

• Chunk your lines of code into groups. If there are several lines of code in-a-row that all help achieve the same small task, you should group them together with no spaces in-between. Then, you can put an empty space before the next block of code.
• Use 4 spaces for indentation. Note that 4 spaces is different than 1 tab. Some people might prefer tabs, or 2 spaces, but for the purposes of this class, stick to 4 spaces.
• You should keep all of your lines of code less than 100 characters wide. If you have a line of code that is wider, consider re-writing it to be in multiple statements on separate lines, or split-up the statement onto multiple lines.

Resources

Generally speaking, all resources you use in your android application (strings, colors, images, animations, etc) should be externalized as resources in the res directory. Exceptions to this rule are:

• If a string is two words or less, you are not required to externalize it, unless instructed otherwise.
• If the content is dynamically loaded from some other resource. For instance, loading a string or an image from an HTTP request.

UI

Generally speaking, all of your user interface layouts should be done via xml layout files, rather than in-code, unless otherwise specified. There may be some occasions where it is completely impractical to lay it out via xml, but do so whenever possible.

Function Structure

When using functions in your program, have each function accomplish a specific task. Don’t try to cram too much functionality into one function. If you find yourself writing the majority of your code for a PA in a single function, refactor. If you find yourself writing one function that is more than 30 lines of code, refactor.