CMPS 144: Computer Science 2

jGrasp Project and javadoc Primer

Preliminaries | Starting a Project | javadoc | What's Next

Preliminaries

Before you get started with a project you should start by thinking in terms of organizing your directories (folders) and files. At the very least, construct a folder and call it CMPS144 into which you will place all your work for this course. NOTE: Get in the habit of naming all folders and directories with names containing no blanks and no special characters, except underscore and dash. Getting into the habit of doing that will facilitate working between MS based and UNIX based systems.

Next, you might want to construct subdirectories for each significant assignment or project. Since the Bowling assignment will be with us for a while, you might want to construct a subdirectory of CMPS144 and call it bowling, CMPS144/bowling. You might want to have a folder, CMPS144/misc, for placing small assignments.

Starting a Project

The first step in starting a project in jGrasp is the one where most people screw things up. Simply stated, every time you think of a project you should think of the project having a home directory. For some projects the resources might be all over the place, but it should have a folder to call home. So, the first step is to use jGrasp's Project menu, select a new project,

and bring up the new project window. Before you type in the name for the project, make sure the New Project window is showing you the directory you want to be this project's home directory,

enter a name for the project and press the Create button. The project should now appear as an entry in its home directory.

At this point all we did was create a project, what will be one of many projects. Only one project may be open at a time, so the next thing you have to do it open a project when you want to work with it. Pull down the Project menu, select Open,

browse through the Open Project find the directory that contains the project you want to open, select the project, and press Open.

When you select a project, the Open Projects window will displat the project and its contents, if any.

While a project is open, as you develop resources for a project you must add these resources to the project by highlighting an item, pressing the alternate mouse button, and selecting the Add to Project from the pulldown menu.

As a project grows all you have to do is make sure you have added all items to the project. Try to keep a project up to date by adding or removing entries in a timely fashion. One of the benefits of carefully managing a project is the ease with which you will be able to construct javadoc documentation for that project. At a minimum, make sure all inerface and classe (.java) files that are part of a project have been added to the project.

javadoc

Perhaps the worse failure of software developers is documentation. The failure is across the board ranging from good user documentation, to good system documentation, to good low level documentation. One place to start is to try to have documentation that provides a good overview of the software resources. This is the strength of javadoc. The javadoc approach is to encourage software developers to document their code while they are developing it. javadoc comments are placed in the source code, they have a simple format:

• javadoc comments begin with /** and end with */
• A javadoc comment for any item (class, method, or attribute) immediately precedes that item
• There are special @ codes, most notably those associated with methods (@param, @throws, and @return). Use them carefully, completely, and well. Using the @ codes carefully will have a very positive effect on the documentation you generate with javadoc.
• Get in the habit of including pre and post conditions with each method and try to follow that up with well conceived assertions and exception handling.

Once you have created the javadoc comments, getting the documentation is easy, just pull down the Project menu, select Generate Documentation, presto, your done.

Any time you want to see the documentation, just go to the Project menu and select Show Documentation.

jGrasp will bring up its own browser and display the documentation. You elaborate on your documentation by improving your javadoc comments and regenerating the documentation. You can do this everytime you enhance the software - adjust the comments to meet the software, and regenerate the documentation.

What's Next

At the University of Scranton we make a big deal about communications skills. Do yourself a favor and take communications skills seriously. Here you are in the CS 2 course. From now on, in every CS course, use javadoc or one of its siblings, cppdoc or phpdoc, and document as much of what you can of all the software development assignments you do and put them on the department web site. I guarantee you that if you do this, and us this as part of your professional electronic portfolio, it will make a difference in your career options.

You might as well get started now. In fact, I will have you post some of your documentation in this course to your departmental website. to do this you need two tools:

• A Telnet Client: Google putty, find the putty telnet client and load it on your computer. You'll need it to log into your departmental file space.
• FTP Client: Find a free or low cost ftp client. Try Download.com or Tucows and find a free or low cost FTP client and use it to update your web space.