Code Conventions for the Java Programming in Android

Readability

Purpose of this lesson:

• Human readability is extremely important.
• Especially important factors: Naming, indentation, conventions.

Humans must be able to read the programs

Source code is read by both the compiler, which doesn't care about your writing style, and people, who care enormously about your writing style.

ALL programmers insist that certain rules be followed. Some of the most important are:

• Indentation. Statements which are contained within something else (a class, a method, a loop, etc) must be indented on indentation amount to the right. There are several styles for this; use one of them.
• Meaningful names. Variables, methods, classes, etc must be given names that mean something to the reader. Use names likea, b, and c only when there is no inherent meaning in a variable -- it's just an abstract number. 
  See Names for a more detailed discussion.
• Conventions are important to follow. There are standard naming, formatting, documentation, and usage conventions for Java. the organization you work for may have additional conventions. Use of these conventions makes program source code much easier for others to read.

Who's going to read your code?

          Instructor. If you're taking a programming course your instructor will care a lot about the indentation and meaningful names. Some instructors have a specific class standard for formatting your program. Others allow a range of standards. None allow chaotic code formatting.

Other programmers. If you work on a project that will ever involve other programmers, eg, for maintenance, you must write in a conventional style. Multi-programmer projects often establish a set of standards for all programmers on the project.

Yourself. Surprisingly many student programs use meaningless, deceptive, or multiple-use variable names. When asked what value is in that variable, they are often unable to tell me. Variable names should mean something clear to to the reader.

Tabs (no) or spaces (yes) for indentation

          The problem with tabs is that there is no single definition of how much horizontal space a tab takes, so what you see in your program may be (and often is) very different from what I see when I look at your program. The indentation may be consistent, which isn't so bad, but if you tab to the comments then it usually doesn't work so well when I look at it. And the worst is mixing tabs and spaces because a change in the tab size guarantees things will not be correctly aligned. The programming convention for Java is to use 4 spaces.

Names

Names should be meaningful and follow conventions

           Source code is read by the compiler, which doesn't care about your writing style, and people, who care enormously about the readability of your code. To be readable, the names should be meaningful and they should follow the Java conventions for capitalization and use of the underscore.

Meaningful names

             Variables, methods, classes, etc must be given names that mean something to the reader (temperature, velocity, ...). Avoid names likea, b, and c unless they are truly without special meaning.

I worked with someone who claimed he couldn't think of meaningful variable names, so used v1, v2, v3, ... He was quite smart, but his programs were a nightmare to read. Fortunately, he soon moved into management.

Sadly, I must admit that some of my own old programs have mysterious names like nbrt, which must have been an abbreviation for something. Using abbreviations isn't necessarily bad, but they must either be commonly understood or documented in comments where the variable is declared.

Single use. Do not use a variable for more than one purpose. Local variables are very cheap so you should always declare a new variable, rather than reuse one for more than one purpose.

Language rules

        Identifiers, which is what names are usually called in programming languages, must obey the rules of the particular programming language you are using.

        Java identifiers start with a letter or underscore and may be followed by zero or more lower case or upper case letters, decimal digits, or underscore characters. Technically the dollar sign is also allowed, but should never be used because it may conflict with compiler-generated internal identifiers.

Conventions

          In addition to being legal, programmers expect identifiers to follow standard conventions. These conventions often vary somewhat from language to language. The standard Java conventions are explained below. Your organization (or instructor) may have additional naming conventions.

Names consisting of multiple words

Because blanks can't be used in identifiers, multi-word names are handled by using camel case in Java, or separating the words with underscores in some other languages (eg Ruby).

Camel case marks the start of a new word by writing the first letter in upper case.

   double dailyAverage;

   int    maximumNumberOfSunnyDays;

A popular alternative to camel case in some languages is to separate the words with an underscore. Altho underscores are a good convention, they won't be accepted in Java programs, with one exception as noted below.

Sun's conventions for Java identifiers

Use the following conventions, which are almost universally followed in Java programs.

• Class names (and interface names) start with a upper case letter and are continued in camel case. 
  Examples: String, JOptionPane, DecimalFormat.
• Variable and method names begin with a lower case letter and are continued in camel case. 
  Examples: dailyAverage, maximumNumberOfSunnyDays
• Constant names should be entirely in upper case, with multiple words separated by underscores. 
  Examples: EXIT_ON_CLOSE, MILES_PER_KILOMETER.

Review questions

The following are all accepted by the compiler without error, but they all should be changed. How?

1. public class celsiustofahrenheit {
2. int maximum_temperature;
3. static double MilesPerKilometer = 0.6;
4. private double compute(double n) {return n * 0.000144;}