ADT's in brief

Which classes do you need to show ADT's for? Well, what is the idea?

The idea here is documentation for reusability. Suppose someone else wanted to use your new class. You need to tell them what your implementation is all about.

• Purpose: what they can expect from this class and each of its methods
• Imports: what classes would they have to make sure they have available if they want to use your class
  (note: if your class is in java, you can assume that they have a JRE and do not need to specify classes available therein.
  However, if you use something not available in the JRE, then the user must know that they need to have it available in their CLASSPATH)
• Exports: what new objects (the new class you are defining) they can instantiate; what new methods they can call

• Pre and Post Conditions: what they can expect (or not) from each of these new methods
        Not the same as Parameters and Returns (discuss)

Obviously, if you are using a pre-defined class, then you do not need to provide ADT information, the writer of that class should have provided it for you. In this case, you are the user and someone else was the implementer. Now, normally you would be expected to provide this information for only the public materials, since the user does not see the private ones. However, in this case, I am grading your whole submission, so I, as someone judging your design, need to see the ADT information for each or your defined classes.

For the methods, it is necessary to give the signature so that a user knows what to pass as parameters when they use this class. Example: myMethod(String name)
If you use javadoc it will do this for you.
(Nice documentation pages and all it takes is using /** and */)

In fact, with javadoc it provides an API page which basically gives you a nice page illustrating your "exports". Specifically, an API page shows what class you are providing and what methods and variables are in it. You still will need to show the pre and post conditions for the methods though.

Often students seem to have a hard time when trying to concretely say what the Pre and Post conditions of their methods should be.
Note: Each method that you provide for a class needs pre and post conditions

• One good technique for Pre-Conditions is to consider what you are not error checking for, and, of course, what you, the implementor, assumed to be true and thus coded accordingly. Sometimes, this is simply that the correct parameters were passed. Note that in object-oriented programming, since everything isn't "passed" through parameters, you should consider if your code accesses any variables of this class and/or some other class. If it accesses them, you should tell the users (via Pre-conditions) that they must be sure in their application at the time of this call that these variables have been instantiated in order for your code to use them.

• For post-conditions, what can the user assume to be true when your code is done? Did you, the implementor change or rearrange any instance or class variables anywhere? If you give this post-condition to someone else to design, did you leave them too much space to change all kinds of things that you didn't intend for them to change? Be clear about the fact that code that implements this method will do these post conditions and nothing more. I.e., everything else stayed the same. If your code has side-effects (a change in another class somewhere) then you should say explicitly that it does this. Nothing should be a surprise to the user of your code. If, in doing a search for something in an array your code sorts the array, then this should be specified. It is a change that other users of your code may need to know. On the other hand, if your code does not change other things, then say that too.
  Another way to look at it: someone should be able to give you PRE and POST conditions for a method and you should be able to be clear on what exact code is expected. Think of it as a contract. If they are vaque in the POST, then you, the programmer, can implement anything you want. POST condiditons should say explicitly what is expected in the method

How about a nice example of how PRE and POST conditions might be useful.

Remember

precondition

• the implementor assumes it to be true...and codes accordingly
• the user must be sure in his code it is met in order to use

Postcondition: an assertion that prevails upon completion of the operation. A description of the results of the actions performed by the operation. It must be accurately and precisely stated

postcondition

• the implementor must make it (through his code) true
• the user assumes it will be true