Java Reference
In-Depth Information
Tip Where possible, you should also put your design decisions in an implementation comment close to
the code itself. For example, if you had chosen a radio button instead of a check box, having an implementa-
tion comment near the constructor for that button will save the person maintaining your code from spending
time trying to decide whether this was the “right” choice or not.
Sun has a difficult task—how do they prove that you wrote the assignment that you sub-
mitted? One step in the process is to have multiple assignments (different business domains),
each with multiple versions (different interfaces to be implemented), so it is unlikely that any-
one you know will happen to have the same assignment as you. Another step is to check that
the information you write in the written exam (where you must provide proof of ID) matches
the design choices document, and that the design choices document describes the code.
Combine these, and Sun can be reasonably certain that the person who sits for the exam is
the person who wrote the code.
It is very important that you write down your design decisions as you make them. If you
leave that task until the end of the project, you will have a hard time remembering what
choices you made, let alone why you made them.
Javadoc
It has been shown time and time again that if the documentation is separate from the code,
then it is often not updated at the same time as the code is updated, which renders it useless.
Javadoc, and similar code documenting tools, were designed to solve this problem. By
putting the code documentation with the code itself, it is much easier to update the docu-
mentation at the same time the code is updated.
But this relies on one major premise—that you write and update the comments at the
same time as you write and update the code.
If you wait until the end of a three-month assignment to do the source code commenting,
you may find that you have another three-month job ahead of you just to finish the com-
ments, simply because you have to reread all your code to work out what you were doing in
order to document it.
User Documentation
In the section “Prototyping the GUI,” we recommended drawing rough sketches of your user
interface before starting the project. One of the benefits we mentioned is that you will then
have a definite design to work toward, reducing the risk that you will end up with a less usable
interface simply because it is easier to implement.
When you write the user documentation before coding, you get the same benefit: you
have described up front what your user interface is going to do, so you have a definite target
to achieve.
You also have a definite end point in mind—when your user interface meets your user
documentation, you know that the user interface should be ready for testing.
User documentation is also where users go when they have a problem, or when they want
to determine how they can do something more advanced. Incorrect or badly worded user
Search WWH ::




Custom Search