What's N?
In Computing Science, there is a need to talk about "some number of" things that will be manipulated. For example to write a program that manages drivers' licenses for a given state, there will be "some number of" drivers' licenses in each state. New York might have 12 million drivers' licenses while Wyoming might have half a million. When developing the program, it should not matter how many drivers' licenses will be stored in the system as the program should handle any of the N drivers' licenses. On the other hand, if a specific driver's license must be retrieved quickly, the system should be tested to handle "any number of" drivers' licenses without significant wait times. As will be discussed later in this reference, computing scientists consider an N of 100,000, or 1,000,000, or even 100,000,000, or more, or less. As it is used in this page, N means "some number of" rules every programmer should practice in order to develop their skills and knowledge in an effective way.
One note to make. At this point, students may not be familiar with some of the coding actions below. Nevertheless, students' habits must include these commandments from the beginning so all students should be checking these commandments regularly as they learn to program.
The N Commandments
Always use self-documenting identifiers
Sixty years ago, when memory was limited and computing was small, people got away with using j, k, l, x, y, z, etc.They didn't really have a choice. But, note that that was sixty (60) years (or more) ago. There is no need or reason to limit identifiers to single letters, or even a few letters, and it takes away from program readability when they are used. For that reason, professional programmers use what is called self-documenting identifiers which means exactly what it says: the variables document and/or explain themselves. They tell a reader or programmer what they mean or what they do, or both.
To begin with, an identifier is just a series of letters; more will be provided on this later in this reference. There are three identifiers most concerning to readers of this reference. First, variables must explain what they are and/or what they store. Thus, variables should be nouns, such as age, gender, name, etc. Second, methods do things so they should be verbs, such as getInput, calcResult, or findCenter, and third, constants are just variables that don't vary in a program so they are also nouns but presented differently with examples such as TAX_RATE, FIRST_ITEM_CODE, or RADIAN_DEGREE_CONVERSION. As noted, more will be discussed on this later in this reference but the habit of using self-documenting variables must start today.
Always use curly braces, and always keep them aligned
Some of the worst possible bugs in programming are caused by missing or improperly placed curly braces. Curly braces must be used for every branching operation, and must look like one of the two following forms:
if( some test )
{
some program action
}
OR
if( some test )
{
some program action
}
Again, more will be discussed on this topic later in the reference.
Never write code on the same line as a curly brace
Readability is the most important product that programmers deliver. Placing code on the same line as a curly brace takes away from this. Example of incorrect operations:
if( some test )
{ some program action
}
OR
if( some test )
{ some program action }
Always make sure the curly braces are aligned and on their own lines, as shown in the above commandment.
Never use an else if where an else would work
As logic is used in programs, students must demonstrate understanding of branching operations by using the correct operations. If a television is on, then it is not off. There are only two choices. Therefore it is inappropriate and redundant to ask the alternative question, as follows:
if( TV is on )
{
watch
}
else if( TV is not on )
{
sleep
}
The correct logic is:
if( TV is on )
{
watch
}
else
{
sleep
}
Never change the state of a variable in a bracket or a parameter list
Due to the way some operators work in Java, issues will arise when inappropriate data state changes are made. The following should never be implemented:
value = array[ index++ ];
value = someMethod( someParameter-- );
On the other hand, adjusting a value for use in an array or method is fine, as shown here:
value = array[ index + 1 ];
value = someMethod( someParameter - 1 );
Adopting this practice will save hours of attempting to track down insidious bugs.
Never declare a variable in a loop
Like some of the others above, creating variables within loops is legal in the language but being legal does not necessarily mean being smart. There are several issues that can arise when variables are declared within loops and they can lead to a lot more time debugging than most folks want to contribute.The following should never be implemented:
for( int index = 0; . . .
{
some code
}
OR
while( some test)
{
int someNewValue;
some other code
}
Never declare part of a for loop
If a for loop is to be used, use it correctly. The basic value of a for loop is to provide a programmer all the looping conditions and information in one place. Do not leave parts out, as is implemented here:
for( ; index < total; index++ )
{
some code
}value = someMethod( someParameter-- );
Instead, use the complete form, shown here:
for( index = 0; index < total; index++ )
{
some code
}value = someMethod( someParameter-- );
If parts are to be left out, use a while loop.
Never use ones or zeros in place of true or false
Again, in the way olden days, ones and zeros, and sometimes other values, were used when true or false was not available in the programming language. Again, again, that was decades ago. Example:
if( some test )
{
return 1;
}
Instead, use the data that was meant to be returned (and is much more readable), as follows
if( some test )
{
return true;
}
Wherever it is possible, place the readable quantity in the code.
Never use unknown numbers in code
There are times in code that a constant of some kind must be used. However, if a literal or actual number or value is used, it can easily lead to difficulty in understanding the code. If there is any question as to what the value means, use a constant, not a literal number, which in this situation, is commonly called a "magic number". Observe the following:
someValue = subtotal * 2.75;
Instead, use of a constant will lead to much more clarity in the code:
someValue = subtotal * STATE_TAX_RATE;
To repeat, wherever it is possible, place the readable quantity in the code.
Always follow the specifications
The Java language has the ability to test for a failure condition with the try/catch operation, and it has other operations that might seem useful to a programmer. However, if this, or any of these operations, are not specified for a given project, don't use them. If there is ever a question on a project specification, talk to your supervisor, or in a course, to your Instructor. Never guess and never use tools that have not been specified. They usually won't work as you expected them to anyway.
Don't always write the specifications
One of the actions programmers will face is using some form of programming documentation such as Javadocs. To be legal and complete, Javadocs places qualifiers in the specification that are not necessary in the code. A good example of this is identifying the source of some data quantity. For example, the String class might be used which can hold a series of a letters (i.e., a string). Javadocs will present this as java.lang.String. However, as a programmer is coding, he already knows that the String object was inherited from the original Java object (like every other class in Java), and this is extraneous information. Don't:
public void someMethod( java.lang.String stringParameter )
Do:
public void someMethod( String stringParameter )
(Almost) Never use the break keyword
The break keyword might be used in several places in a program. However, in most cases, use of break is evidence that the individual has not figured out effective logic yet. The one and only place to use the break keyword is in the switch statement after each case condition. There is no need for it anywhere else.
Never use the continue keyword
While the break keyword is clear evidence that a person has not achieved an understanding of logic, the continue keyword is evidence that the person has never learned about logic. It is a patch, and not welcome in the professional programming environment.
Never use the return keyword without something to return
There are circumstances in a program where something needs to be returned from a method. There are other places where folks who do not understand logic feel they can just return from their current location rather than developing appropriate logic for the circumstances. In spite of what Nike™ says, just don't do it. Here is an example of what not to do:
if( some test )
{
return;
}
On the other hand, the following is perfectly appropriate:
if( some test )
{
return calculatedValue;
}
(Almost) Never input or output data from a method
If a method is specified to acquire input (I) or implement output (O), then it should conduct the specified I/O operations. However, methods should never acquire input or provide output under any other circumstances. Methods are member functions which are given the necessary data for an operation, and are required to return the result of said operation much as any mathematical function would do. There is nothing in any mathematical function that calls for asking users for data or displaying it to the user after the calculation is conducted. The process is done, and the results are returned. Nothing else should happen in the method, again, unless it is specified.
Always write methods on their own line
Which is to say, never write methods anywhere else, such as in parameter lists or array index brackets. Since a person reading this code cannot observe the output of these actions, debugging becomes very difficult. This is also readability issue. Don't:
value = array[ someMethod( someParameter ) ];
value = someMethod( someOtherMethod( someOtherParameter ) );
Do:
someIndex = someMethod( someParameter );
value = array[ someIndex ];
someParameter = someOtherMethod( someOtherParameter );
value = someMethod( someParameter );
Yes, it is more code, but it is also eminently readable and folks whose job it is to debug code get some relief.
Never leave a code block empty
Like using break or continue, the use of an empty code block means the programmer hasn't figured out the correct application of logic yet. It is not necessary and it is a waste of code. Don't:
if( some test )
{
empty block
}
else
{
some code processed here
}
Do:
if( !some test ) // use of NOT operator
{
some code processed here
}
In this case, it is significantly less code but there are lots of other ways to handle this circumstance. Enjoy the win.
Never use a main method in a data management class
As mentioned previously, this reference will start out using static operations where the problem solving code will all be in one file which holds the main method. However, once real OOP data management classes are implemented, main methods must always be in a separate file, and never in the local data management file. Some inexperienced programmers will put the main in their data management class "for testing". However, these programmers will end up spending more time taking it back out and testing the class correctly then they will have ever gained trying to short cut the process.
Never let your code go off the page
One of the more difficult issues between programmers is using different editors. In theory, this should never be a problem. However, there are two conditions that can bring programmer harmony to a halt. First, folks who use tabs in their code are likely to experience problems when their code is opened in another programmer's editor. Tab settings are regularly different from one editor to the next so the code that looks fine in one editor might go completely off the page for another. The problem in academia is that unlike industry where several programmers share code, student programmers don't experience this so they don't see the problem. However, even in academia, students' code is viewed in other editors when it is graded. If the code goes off the page during grading, students may not get full credit for their work. In the Getting Started part of this reference, instructions are given for setting tabs to spaces in the Eclipse editor. This is a worthwhile endeavor for anyone who intends to work with others in software development (and that would be everyone who works in software development).
The other problem is that with or without tabs, if code goes past 80 characters in the editor, it may not print correctly, or be viewed correctly, and in some cases in some editors, code that goes past 80 characters may not be viewable at all. Again, this is very inconvenient for programmers whose code is reviewed by peers, supervisors, or in the case of academia, their graders. Again the Getting Started chapter demonstrates how to set the 80 character line in the editor and that is another worthwhile endeavor.
Never use the ternary operator
There is an operation in the Java language called the ternary operator. It essentially makes a one line operation out of an if/else statement. There are those who would think this is pretty cool but those folks have never spent time in a professional programming environment. This rather old time operation is a significant contributor to bad readability and should never be used. The compiler will take care of optimizing code but a programmer's job is to write code for other programmers to read, analyze, maintain, extend, and sometimes debug. Always use the more structured if/else statement and help your fellow programmers keep you on their "friends" list. Don't:
value = <some test> ? <result if test is true> : <result if test is false>
Do:
if( some test )
{
value = <result if test is true>
}
else
{
<result if test is false>
}
Conclusion
From the looks of it, N equals 20 in this case. However, it could grow or be modified as times change. N can change in any environment. However, students who follow the above commandments will never have difficulty creating readable, effective, and professional looking code. Somewhere down the road, some students may adapt these commandments to their professional practice or they may adapt their professional practice to these commandments. The critical point here is that, especially in the learning stages, students need solid references as well as the structure that must be promised in all code they write. Enough said.