So I am finally approaching an end of my project, code is almost complete (I got few new ideas like shutdown hooks), and documentation written (userguide is done, choices still need revision). However few points are unclear to me and I would be glad if I sort them out.
1. What did you guys write in userguide.txt? Mine ended up being only 7kb, which seems pretty small to me, however I believe the application is indeed small from users' point of view, thus not much info is necessary. I explain overview of application, how to run it (with different modes), how to run server, and how to use client (book and search). Did I miss anything?
2. I made my javadoc to generate documentation for default and private classes/methods/packages. If I only make to to generate public constructs, then a lot of things like classes that compose Facade of my Data class will be missing. Is there anything wrong with this approach?
3. I also documented every single private variable too, for consistency.
4. Can I only reformat DB interface? It really looks ugly to me, having bunch of one-line comments above every function instead of javadoc.
5. I made my error messages pretty technical, since to fix then it is better to have technical info. The only message that I have non-technical is the message that the record is already booked, thus user must refresh the list of records.
6. In description of database file it says to me that all strings of records fields which are less than maximum length of the field are null terminated. However analyzing the file with hex editor, I saw that instead of being null (%00) terminated, they are padded with %20, which is ASCII for space. So what should I pad my fields which are too short with in my create method of Data class? Should it be %20 or %20? Right now I have it declared as a variable, so it is very easy to make a change.
7. My UI is unresponsive during the call. I made it this way since I believe requests will be fast enough for user not to feel it, and user is not supposed to do anything until the requests are done anyway, like they should not search or book when another search or book is done. Is this ok or I better change it? (Ok, the main reason for doing this was because I was lazy )
I can comment on the questions that were similar to my assignment. You have design differences that I am sure are ok but a more experienced rancher should answer.
1 I documented my error messages as well. i.e. Under what circumstances the error is displayed and the corrective action to be taken by the user.
3 Me too.
4 I did not touch the supplied interface. I reproduced it exactly. I explained in my choices.txt that it was a common interface so I did not alter it in any way.
5 same here and see 1
6 My assignment only updated the owner field. It either contained a name or spaces.
First of all, I am waiting for grading, so my answers might not be 100% right, but I hope they help you a bit.
1. I've added the "Troubles" section which says what you should do if you bump into a specific situation (no response from server, wrong port number, room already booked situations, etc.)
2. I've generated javadoc from package level - ommitting private artifacts, as I decided they are too low-level for javadoc documentation in this case.
3. Me too.
4. I did reformat the DB interface without touching the code (just changed the implementation comments to Javadoc ones and added @param, @throws, etc.). I justified my decision in choices.txt
5. I did not put any technical messages in the GUI. I wrapped low-level exceptions into the business exceptions which are presented to user (so there are only RoomAlreadyBookedException, RoomNotFoundException and StorageException instead of SecurityException, RecordNotFoundException or FileNotFoundException. I justified my decision in choices.txt. I believe that the technician should read logs or low-level system informations (like stacktraces) but user shouldn't be informed about those.
6. I've also analyzed the text file in Hex editor, and decided to add spaces when inserting, which I justified in choices.txt
7. Mine is also unresponsive. I've added progress bar when long-term operation might occur (establishing connection) and change cursor to waiting mode when shorter operations might occur (exiting application). I justified these decisions in choices.txt.
1/ user guide is 16 Kb, plain text, contains also information about possible answers and a bit of "plain text" markup to increase the readibility.
2/ No, I did the same
3/ I did that too
4/ I added some file and class comments, but didn't reformat the DB interface
5/ I have user understandable messages, nothing technical there (that's not the intention in my opinion: if you want technical info, use a logger)
6/ I used space padding
7/ I didn't handle a long-term operation, because it was not required and not specified how such an operation should be handled (maybe the business people want a timeout of 5 seconds)