Development Standards

This lab will introduce you to JavaDoc, as well as some programming standards.

JavaDoc
To Get Started ...

Download the jar file StopLight.jar to your csci/201 directory and unjar the file (Help). Create a new project called StopLight and mount the StopLight directory that was extracted from the jar file in the step above (Help).

JavaDoc is a standard for providing automatic documentation of the programs you write. You may have noticed that NetBeans uses JavaDoc to display a pop-up window when you are typing. NetBeans also has the ability to generate JavaDoc.

We are going to use an external web browser to view the JavaDocs we generate, so begin by verifying NetBeans' choice of external browser. (This should only be necessary on a Linux box without Netscape.) In the NetBeans Window, select Tools and then Options. In the pop-up window, scroll until you find Web Browsers, which is directly below ServerAndExternalToolSettings. Underneath Web Browsers select the first External Browsers option, this should be External Browsers (UNIX) on a Linux machine (External Browsers (Windows) on a Windows box). Verify that the appropriate browser is designated; on our Linus boxes, the designation should read: mozilla {params}. Change the designation if necessary.

While it is not readily apparent why you would want to go through so much trouble for a small program, when you are working as part of a team writing thousands of lines of code, standard methods of documenting your program are crucial.

Your Assignment ...

Open the StopLight.java file. Click the Tools menu, and select Auto Comment. In the left pane, select the public static void main() entry. This will pull up the JavaDoc creation screen for the main() method.

panel

In the JavaDoc Comment Text box, enter the following:

Creates the StopLight Frames and starts the Control
threads.  This method is called when the program is started to load
the other classes.

comment text

Now click the New button. Select the @param option and click OK. Now for the Parameter field, click the drop down arrow way to the right of the field, and select Args.

comment text param description

For the description field, type:

This gets the command line arguments passed by the user.

param description

Finally, close the Auto Comment screen.

Notice that new comments were inserted into your document just before the start of the main method. These comments are in the special JavaDoc format. Many different programs (including NetBeans) can use this information to make automatic documentation. For instance, to generate a web page containing information on your program, click the Tools menu and select Generate JavaDoc. After a short period, NetBeans should ask you if you want to view it, click Yes.

Instructor Checkoff ...

Show your lab instructor your beautiful JavaDoc page.

Capitalization

In case you haven't noticed, Java is a case sensitive language. This means that when you give things names, you have to pay attention to the letters you capitalize. Correct capitalization can make it easier for you to work with others, as well as save you time in the long run.

Here are some capitalization standards you can use in your coding:

Section Standard
Class Names First Letter of each word in Uppercase (ex. class MyClass)
Instance Method and Variable Names First word in lowercase, first Letter of each subsequent word in Uppercase (ex. void debugDumpToScreen)
Package Names All lowercase (ex. class java.lang. )

Of course, you can make up your own, but it is important that you adhere to some sort of standards in your coding.

Spacing

Which is easier to read, this:

int x=myClass.showYourself(y);
     if( x<= 14){
System.out.println("something");}else{
System.out.println("Something2");}

or this:

     int x = myClass.showYourself ( y );
     if ( x <= 14 ) {
          System.out.println("something");
     } else {
          System.out.println("Something2");
     }

As you can see, the spacing you put into your code can have a big difference on its readability. This is a skill you learn with practice, however, notice how we indent code inside blocks ( {} ). This way you can easily tell where the block begins and ends.

Naming

There is only one rule in Naming, give everything a meaningful name. Try to make it so that whoever is using (or reading) your code can get an idea of what the class/method/variable does by its name. In other words, numberOfJobs is a much more descriptive name than temp