Writing high-quality programs using good style is important, for many reasons. Professional programmers need not only to be able to read and understand their own code, months or even years after originally writing it, but also to be able to read and understand code written by others, oftentimes in the absence of the original author. Programmers who write code in a clear style with adequate documentation benefit not only themselves, but all other current and future members of their team. There is nothing more frustrating as a programmer than inheriting responsibility for someone else's code, only to find that the code is designed poorly, written cryptically, and documented shabbily (or not at all!). Having inherited plenty of code in my career that exhibited some or all of these shortcomings, I would be remiss if I did not insist that your code was better.
Of course, it's not enough for me to say that you should "use good style" or "write high-quality programs." These are terms that are obviously open to interpretation. I have adopted a set of specific standards that I would like you to follow when writing your Java code in my course. These standards are framed by one guiding principle: A program that can be read easily is one that can be understood easily, by the author as well as others. The standards are described in the list below.
- Matching opening and closing curly braces should be aligned in the same column. This means that the opening curly brace which follows an if statement should appear directly below the letter i in if, and not on the same line as the conditional expression.
- All statements within curly braces should be indented four spaces (or one TAB character) relative to the brace. A statement should not appear on the same line as the opening curly brace. (It's a good idea to be consistent in using either spaces or TABs for indentation, but not a mixture of both.)
- The names that you use for variables, parameters, methods, and classes should be meaningful (and, ideally, should be fully-spelled-out English words). Exception: Counters or other loop control variables may have simple names such as i or p.
- All constants in your program should be defined and named meaningfully. For example, if you were writing an array implementation of a stack with a hard-coded maximum size of 256 elements, define a static final field such as MAXIMUM_ELEMENTS, and use that field in your code, rather than the literal integer 256. Exception: A loop control constant, such as one that sets a loop counter to zero to begin with.
- I should be clearer about what it means to name a constant "meaningfully." The objective of naming a constant is to introduce a name that explains what it means or what it will be used for. Using the name ONE_HUNDRED for a constant whole value is 100 doesn't do anything to make your code more understandable or more resilient to future changes. (Why is the value 100? What is the constant's purpose? Is it the minimum size of a GUI window? Consider naming it MINIMUM_WINDOW_SIZE, then.)
- Naming conventions for classes, members, and constants:
- Class names should be capitalized. Class names with multiple words should have each subsequent word capitalized, with no underscore separating the words. (e.g., Song, ReggaeSong)
- Names of class members (methods and fields) and the names of local variables and parameters should begin with a lowercase letter. Subsequent words should be capitalized, with no underscore separating the words. (e.g., playSong(), songTitle)
- Named constants should be named using all capital letters, with underscores separating the words. (e.g., EULER, MAXIMUM_ELEMENTS)
- Every member should be declared using an access-control modifier (e.g. public, private, or protected). Leaving off the access-control modifier causes Java to revert to the strangely-chosen default of "package scope," which is not appropriate for the work we're doing in this course.
- Whitespace should appear between each method argument and around each binary operator. For example, createFile("alex.out", WRITE) instead of createFile("alex.out",WRITE), or a + b instead of a+b.
- One single line of code should not be inordinately long. What constitutes "inordinately long" is largely a matter of taste, but a good rule of thumb is not to write lines of code that are longer than 80 characters. Don't be afraid to break up long lines into multiple lines. For example, if you have a method call with fifteen parameters, put some on one line, some on the next, etc., such that each line is no longer than 80 characters. (This requirement is partially motivated by an anachronism — printers that will print only 80 characters per line — and partially motivated by the fact that it is much easier to read a program if horizontal scrolling is unnecessary.)
- Every class, method, and field should have a comment which briefly explains its purpose. In the case of methods, some explanation of the meaning of the method's parameters is expected.
- Within the body of your methods, code whose purpose is not readily obvious should be commented. It is not necessary to include a comment on every line, nor is it necessary to explain something that would be obvious to someone who knows Java but is unfamiliar with your program.
- It is appropriate to have one comment which explains the purpose of a chunk of several lines of code, when you have a chunk that is complicated. It's even better, when you have a chunk of several lines of code that requires a comment, to consider putting the code into its own method with a meaningful name and meaningfully-named parameters.
A good example of many of these coding practices can be found by looking at the various starting points provided for each project. Some of these files do not follow all of the rules above, particularly the rule regarding a comment on every method (since we expect you to write these comments yourself, in some cases), but they are still a useful way to see many of these rules in action.