CISC370, Homework H03, Summer 2007:
Distributing Your Source

Due: Tuesday, 07/03, 11:55pm

Better: Try to get it done by noon, Thursday 06/28
so that you can ask questions in class
on Thursday if you run into problems,
and get a start on H04!

Note that H04 is due
Thursday 07/05 at 11:55pm!
So you need to get done with this one!

Introduction

In this homework assignment, we'll take several steps towards a more professional approach to software development than you may be used to from previous CIS courses.

What you may be used to is this:

• You get a programming assignment that asks you to write some code
• You write the code, and then produce a script. You turn in this script, and a source listing.
  • (You might or might not turn in an electronic version of your code)
  • You know that your TA—and possibly your instructor—are the only humans other than you that will ever see your code, and they will probably only look at it once.
• The TA looks at the printout or the script, and gives you a grade
  • He/she might or might not actually compile and run your code
• Your code is thrown away, never to be seen or used again

What we will be doing instead:

• You get a programming assignment.
  • You may or may not get a code distribution along with that programming assignment, in the form of a tarball or zip file.
• You develop some software to solve the assignment
  • This may be from scratch, or it may be as an extension to the distribution you were given
• As you develop, you publicly release a distribution of the software via a web site,containing
  • a brief description of the software
  • a link where someone can download your distribution via a tarball or zip file (or both)
  • a link to JavaDoc for the software
  • a link where folks can browse the source
• You understand that
  • future assignments may build on this code
  • that in a future assignment, you may to build on someone else's code
  • that in a future assignment, someone else in the class may be building on your code
• You understand that this means you may want to put a bit more time and thought in your code than you have in the past.

How Ant, JUnit, and JavaDoc, SVN will support this approach

Open Source means "distribute your source"

If you are doing open source development, you have to distribute your source code. This is usually done in the form of a tarball (gzipped tar file), or a zip file.

In this homework, we'll see how we can automate this process using Ant.

Open Source means: "document well"

Distributing your source means other folks need to be able to use it. That means you need to document well. In this homework assignment, we'll learn how to use Ant and Javadoc to help automate this process.

However, this process cannot be fully automated. It requires discipline, thought, creativity, and some effort on your part. It is a process that is both a skill and an art. (More on this below)

Open Source means: you need to test!

Other people will be using your code. So you would really hope you find all the bugs before you distribute it.

We'll get more practice with using Ant and JUnit to do test-driven development in this homework assignment.

Open Source means: organizing the namespace

You may want to use software by folks you've never met, and they may want to use your software. But, in a given Java program, you can't have two classes with the same name. How can you be sure you won't have any names that conflict?

In this homework assignment, we'll learn how to use the package feature of Java to address this problem.

Open Source means: code that changes over time
Open Source means: collaboration among multiple programmers

We won't take these two items on in this particular assignment, but soon we'll be learning SubVersion: a source code revision control system that will help us with those two particular aspects of professional open source development.

More Background (Required Reading—don't skip this!)

The Art of Documenting Well

The ability to write good documentation is not something I can directly pour into your brain like a "fact" (e.g. "Dover is the capital of Delaware", "Sacramento is the capital of California" ) —rather, it is a process—an art and a science that you have to teach yourself. I can only serve as a guide, and a coach.

However, if you talk to real-world professional programmers, they'll tell you that this is a very important real world skill! So if we want you to be a highly qualified software professional when you graduate, we need to take this on together.

The code distributed with this homework assignment is my attempt to point you in the right direction. But to learn to write you will have to study it, and ask yourself—and me, and each other—what makes the documentation good or bad.

You'll probably have to write lots of bad documentation, and listen to me explain how to make it better, before you can start writing good documentation. We'll need to have lots of conversations about what distinguishes good from bad documentation—recognizing that it is difficulty to come up with "absolute rules" about something that is rather subjective.

What is this " Organizing the Namespace" stuff?

Suppose you find two classes out there that you want to use in your program:

• One class is called PhotoBuffer and it is used for reading pictures from a digital camera.

• The other class is called PhotoBuffer and it is part of some software that converts between JPEG and TIFF.

What? They are both called PhotoBuffer?

Yes, and furthermore, you need to use both of them in your code. How did they end up with the same name? Easy: they were developed by two different programmers who never imagined that they'd be used in the same program.

Fortunately, there is an easy solution to this problem in Java—it is called "packages". Every time you develop a Java class, you can put it into a package that has a unique name in all of the world, and you can be sure that there will never be a naming conflict.

How can we be sure that the name is unique in all the world?

We choose a package name this way:

• We start by choosing a package name associated with UD. Now ,we are only worried about conflicts with other folks on the UD campus. We do this by using the domain name of UD, backwards: edu.udel
• Then, we add to that, the number for this course: edu.udel.cisc370
• Then, we add your username (which is unique among all UD students): edu.udel.cisc370.jstudent
• Finally, we add a name for a package of related classes that we will group together: edu.udel.cisc370.jstudent.Formats

Actually, we could leave out the cisc370 part, but it is good to include it, to distinguish Java packages you develop for this course from those you might develop for another course.

What this looks like in the code

At the top of each of your source files, the very first line of code (other than comments) should be:

package edu.udel.cisc370.jstudent.Formats;

You also must create a subdirectory tree that mirrors this package name, and put your code in that subdirectory tree, like this:

> mkdir -p edu/udel/cisc370/jstudent/Formats
> cd edu/udel/cisc370/jstudent/Formats
> emacs MyClass.java

Compiling then gets a little trickier. If you stick with compiling with Ant (following the example in this homework assignment) it should all just "work out", but if you try compiling at the command line, you'll need to learn a bit more.

Where can I learn more?

All the details about using packages, and compiling at the command line with packages are explained very nicely in your textbook! I strongly encourage you to look over this before starting the assignment.

Required Reading

• The pages listed above in HFJ that explain "packages".
• Chapters 1-4 in Java Extreme Programming Cookbook.

You may collaborate—same rules as for H02

Please review the rules from H02 regarding collaboration.

What you'll do in this assignment

In this assignment, you'll work with a package called Formats, containing two classes.

• The first is called FormattedTitles. This class contains only static methods that return results of type String.
• The second is called FormattedTitlesTest, and contains unit tests for the methods in FormattedTitles.

FormattedTitles is used to produce titles that are formatted nicely. For example, you might want to center the words "Welcome to my program" in a field of 80 characters, like this:

                             Welcome to my program
12345678901234567890123456789012345678901234567890123456789012345678901234567890

Here, we have 29 spaces before the words, and 30 afterwards, approximately centering the words in the 80 character wide space. The FormattedTitles class can do this with the following code:

System.out.println(FormattedTitles.CenteredTitle("Welcome to my program",80));

The class has three other methods to do various kinds of formatted titles. You can browse the JavaDoc for this class here: http://www.udel.edu/CIS/370/pconrad/07J/hwk/H03/Formats/javadoc/

In fact, you can find a complete distribution of this package, at the following link:

: http://www.udel.edu/CIS/370/pconrad/07J/hwk/H03/Formats

Just one problem: the job isn't finished! That's where you come in...

So, here's a "to do list" for this package:

• While one of the methods passes its JUnit tests, several others are only in stub form. You need to finish these methods.
• At least one of the JUnit tests has a logic error in it—that is, the test itself is incorrect.
• One of the methods doesn't have any JUnit tests yet. You need to add those tests.

But, before you can do that, you need to set up your development environment for this project.

Set up your development environment

Here's what you need to do:

1. Setup a directory on strauss under the directory called something like ~/cisc370/h03.
2. Get the tar or zip distribution, and unpack it into this directory.
3. Type "ant" and see the menu of options
4. Try the "ant dist" option.
5. After typing the "ant dist" option, do the command chmod -R a+rx ~/public_html/cisc370

If you do, you should then find that the web link below (after you change youruserid to, well, your user id)

• http://copland.udel.edu/~youruserid/cisc370/Formats

then has a distribution of this code, just like the one under the link

• : http://www.udel.edu/CIS/370/pconrad/07J/hwk/H03/Formats

Change the package name

The next thing you should do is change the name of the package from edu.udel.cisc370.pconrad.Formats, substituting your own userid in place of pconrad. This will require

• some changes in the directory structure of your unpacked code
• some changes in the source code itself
• some changes in the build.xml file.

What exactly these changes are is something I'm leaving as an exercise to you. Figuring this out will require you to do the reading about packages in your HFJ textbook, and the reading about Ant and JUnit in your XP Cookbook.

Go through the todo list, item by item.

(The todo list appears above. There is also list of hints in a comment in both the FormattedTitles.java and FormattedTitlesTest.java source files.)

Then when you are finished with that to-do list, see if there is anything else that needs to be done for this package to be usable. When you are satisfied that it is complete, submit it, following the instructions below.

Finishing and Submitting

Submit your work on WebCT for the assignment marked H03. Upload and submit BOTH

• a single H03.txt file, which is a script of your programs.
• a single H03.tgz or H03.zip file, containing all of your java source code, and where applicable, sample input files. (It doesn't matter whether you submit a tgz or zip file—only one of the two is required.)

Your tar or zip files should NOT contain your .class files—but if you followed the build.xml example properly, your "ant dist" task should create a tarball and zip file automatically that is in the proper form.

In addition—go to the Wiki page named 07J_H03, and make sure that there is a link to your distribution on that page.

Think carefully about your scripting strategy.

Re-read the notes from H02 about scripting before you do your script.

Hint: A good practice would be to incorporate your scripting strategy into an Ant target, so that when you go to script, the process is automated!

Reminder: Submit your code both in your .txt file and in your .tar file

A reminder: even though your distribution file contains your Java source, you are still required to "cat" this source code in your .txt file, and submit it in both forms. If you do not, you will lose points.

Here's why: Submitting both allows your TA the ability to

• print one file (your .txt. file) and have some place to write comments on all of your code
• compile and run your code without having to tediously extract it from your script file.

Of course, the two should agree—if they don't, that's also a potential grading deduction. So if you make changes to your code, be sure that you redo both your script, and your tar/zip file.

Grading Rubric (100 pts total)