• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

NX: choices.txt (Lazy bum vs. Please shut him up!)

 
Ranch Hand
Posts: 196
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Anyone else having kittens trying to decide how long the choices.txt should be?
I mean I even have a terminology section explaining my use of the word recordSet (cos it technically isnt a set) etc. Why did I call each record a Record rather than a Contractor object.....
My locking section seems long, and yet somehow I worry it isnt long enough! My client section is pitifully short because quite frankly it was a no brainer. I mean how many alternatives can you consider for such a simple interface? Why did you use MVC ... err cos they pretty much tell you to when they say you MUST use a JTable. I mean you have M and V already, you have to try hard not to add C to that
I just know im either gonna bore my examiner to death or insult him with brevity
 
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi Morgan,

Originally posted by Morgan Bath:
Anyone else having kittens trying to decide how long the choices.txt should be?


Follow Frankie Cha's advice:

There is no end to documentation so I told myself just stop doing it when more than 80% is done.


I had about 12 or 13 pages of text for my choices.txt file. I needed a good editor. He could have got that whittled down to about 5 pages. Pity the poor grader, nobody really wants to read this stuff. Pretend the choices.txt document is a test and try to write the first draft completely in 2 hours. Favor bulleted points in support of your design decisions instead of full paragraphs. Go back over your draft and make sure no major points are missing. Add the missing points. And then, most importantly if you feel you're 80% done, you're done.
Hope this helps,
George
 
town drunk
( and author)
Posts: 4118
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I suggest just under a page.
M
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Max Habibi:

Originally posted by Max Habibi:
I suggest just under a page.


One can probably say everything that's necessary to say in about a page. (Of course that means that that page is going to be chock-full of content and your explanations are not going to be exhaustive.) If you're naturally verbose (think me or Javini ) then it's going to take a fair bit of your time to condense down to one page. I think in that case you're OK submitting more than one page, but 5 pages should probably be the outer limit. It's not a question of being lazy but of being concise. Remember, you're not explaining your design to someone off the street, you're explaining your design to someone who grades these things and has probably seen quite a few of them in his time. So your emphasizing what makes your design different from a "typical" solution, rather than explaining the basics of the project. The grader already knows the basics, he wants to be told about the differences, what sets your application apart from the others.
Hope this helps,
George
P.S. See this illustrates the difference: it took me a long paragraph to say the same thing Max said in a sentence: "I suggest just under a page." Emulate Max, not me, and I think you'll be better off in this situation.
[ February 16, 2004: Message edited by: George Marinkovich ]

 
Morgan Bath
Ranch Hand
Posts: 196
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Just under one page ... I cant order pizza on the phone using so few words!
Ok, ill try But did you include any other documentation sort of extra with that page so that IF the examiner wanted he could go deeper? choices.txt & idiots_guide_to_my_code.txt
 
Morgan Bath
Ranch Hand
Posts: 196
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by George Marinkovich:

So your emphasizing what makes your design different from a "typical" solution, rather than explaining the basics of the project. The grader already knows the basics, he wants to be told about the differences, what sets your application apart from the others.
[ February 16, 2004: Message edited by: George Marinkovich ]


And if your solution isnt different? I mean lets face it if you tread the path of least resistance you tread the path of 99% of people going your way.
 
Max Habibi
town drunk
( and author)
Posts: 4118
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator

Originally posted by Morgan Bath:
Just under one page ... I cant order pizza on the phone using so few words!
Ok, ill try But did you include any other documentation sort of extra with that page so that IF the examiner wanted he could go deeper? choices.txt & idiots_guide_to_my_code.txt



I'm merciless when it comes to my own writing, so I tend to rewrite a lot. Write down everything you want to say, then pair it down until a passing friend can follow it(and possibly answer questions about it).
In other words.... be concise
M
[ February 16, 2004: Message edited by: Max Habibi ]
 
Morgan Bath
Ranch Hand
Posts: 196
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Had a thought: How about a compromise? What about a short concise choices.txt, a short concise readme.txt. Then a fairly in depth usermanual.txt & user manual popup window on the gui. Lastly a fairly in depth programmers_manual.txt.
The last could cover the ins and outs, whys and wheres of the code. A manual for people wanting to alter or maintain th code. This is a 'best practice' I do commercially any way and the examiner can simply ignore it if he or she so wishes. The critical thinking is covered in choices.txt, and the exact implementation details are left for the other.
They wont mark you down for that surely, and you cover your bases just in case the examiner isnt quite sure what your thinking was in having overloaded lock and unlock methods
 
Morgan Bath
Ranch Hand
Posts: 196
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Ill give an example of my dilema :
will the examiner know the difference between the Adapter pattern and Bridge pattern? Should i do a brief 2 sentence description of the difference or is this insulting?
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi Morgan,

Originally posted by Morgan Bath:
Ill give an example of my dilema :
will the examiner know the difference between the Adapter pattern and Bridge pattern? Should i do a brief 2 sentence description of the difference or is this insulting?


Which one are you using? I would only talk about the one I was using. I would assume the examiner knows the standard design patterns (at least the ones from Gamma, et al.) and doesn't need the idea behind the pattern explained, just how you are using it (that is, which of your classes are involved). For example:


The DataAdapter class is used as the common interface for both local and remote database access. It implements the adapter design pattern by adapting the DataAccess interface to the DBMain interface, which was provided by Sun and cannot be changed.


No need to mention the Bridge pattern if you're not using it in your design. It's not wrong to mention the Bridge pattern, but is it relevant to your design if you're not using it?
Hope this helps,
George
[ February 16, 2004: Message edited by: George Marinkovich ]
 
Morgan Bath
Ranch Hand
Posts: 196
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I had no classes come with my assignment, only an interface, and no insistance that my client even use that interface, so Adapter class is not really approptiate for me Im using a bridge pattern to hide the implementation details from the client. The database offers a lot of functionality that the client really doesnt need to see. It doesnt need to know about lock, unclok or update, it just needs to book()
Basically I have:
Data implements DBMain, DBServices
then:
LocalBridge implements DBBridge & 'has a' DBservices.
RemoteBridge implements DBBridge, Remote & 'has a' LocalBridge.
But anyway, your point is valid, I wont mention the adapter pattern anyway. But to keep this on topic, would it be a good idea to have the reason for using the bridge in the choices.txt, and a description of its implementation in the programmers_manual.txt that I mentioned before? I get the snappy bullet points in one, and the long winded details in another document that the examiner is free to ignore.
I know im trying to cover my ass from all directions here ... but im paying for the exam myself. I aint paying for it twice
[ February 16, 2004: Message edited by: Morgan Bath ]
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi Morgan,

Originally posted by Morgan Bath:
Had a thought: How about a compromise? What about a short concise choices.txt, a short concise readme.txt. Then a fairly in depth usermanual.txt & user manual popup window on the gui. Lastly a fairly in depth programmers_manual.txt.
The last could cover the ins and outs, whys and wheres of the code. A manual for people wanting to alter or maintain th code. This is a 'best practice' I do commercially any way and the examiner can simply ignore it if he or she so wishes. The critical thinking is covered in choices.txt, and the exact implementation details are left for the other.
They wont mark you down for that surely, and you cover your bases just in case the examiner isnt quite sure what your thinking was in having overloaded lock and unlock methods


I'm not trying to stifle your creativity and if you want to do all that you propose you're probably not going to get marked down for it. As the long as the examiner can find all the required documents in the places specified by the packaging directions in the assignment instructions, then there's probably not going to be a lot of heartburn about having extra documents in there as well. But the point I'm trying to make is that you can do very well (grade-wise) by simply providing what is asked for in the assignment instructions. I don't think you'll be marked down for having an elaborate, verbose choices.txt document (I wasn't and mine was a rambling 12 pages). I'm just trying to give the impression that if someone's design document is 3 pages long, that they won't be assumed by the examiner to be a lazy bum simply because it's only 3 pages long. If it's 3 pages of good information the examiner's reaction is likely to be: "Whew! Thank goodness this candidate knows how to present the necessary information without a lot of exhaustive explanations and didn't waste my time by making me wade through 12 pages like that George character did."
There are some obvious major topics you want to cover: why did you pick RMI or sockets? why is your locking scheme thread-safe? how do you implement the search capability? how do you support local and remote database access? how do handle exceptions in the client that were thrown from the database code? etc. Minor topics you can include or not at your own discretion. If you think it's a minor topic the liklihood is that the examiner will think so too, so if it's not included in the document it's not likely to be missed. If you think you made a simplifying assumption but you're a little queasy about whether it was right to do so or not, by all means try to justify it in the document. If you decided to implement the Sun-provided interface in the Data class, then you probably don't have to mention that as it's explicitly required by the assignment instructions -- not much of a design choice there.
Yes, you could provide a readme.txt file. But if you don't, the examiner isn't going to say: that little weasel Morgan, he didn't provide a readme.txt file I didn't ask for, watch what I do to his documentation score, bwaaaaaahhhh!!! The time spent writing a readme.txt file could probably be better spent re-editing your design choices document. Or if you feel your documentation is 80% done, then it's probably done.
I'm trying to get people away from feeling that if they don't provide something extra that they're not doing a good job. Of course, if something is required, like the design choice document, and people provide a really poor one, then they're not doing a good job and I hope they realize that and fix it before they submit. I don't believe that providing extra stuff compensates for poor quality required stuff. Take the time spent doing the extra stuff and use it instead to improve the quality of the required stuff.
Hope this helps,
George
 
Morgan Bath
Ranch Hand
Posts: 196
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
I totally understand George, but my guess is you will totally understand when I say I am panicky that what is obvious to me, might not be obvious to him. My documentation to customers is based upon the sound and well proven theory that all customer are idiots that got to where they are today by utter luck, kissing butt or satanic pact. I never write "Check your computer is plugged in ...." but im often tempted
I have the free time at the moment, I may aswell include a programmers guide for the few hours extra work. He can ignore it. Or if he has some doubts about one thing perhaps it will be the difference between him thinking my design blows or not At least if i loose marks for something I wont be thinking "perhaps if Id just explained this in more detail ....."
Besides I often find doing this makes me realise something id missed.
 
Morgan Bath
Ranch Hand
Posts: 196
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Ok down to four A4 pages with 99% of it being short bullet points. Ive also decide to go back to my code and change a few names for clarity.
eg I use terms like recordSet for the LIST of records .... old habit.
Also I use the word Adapter in classes that are not Adapter pattern, but are in fact Bridge pattern. This is mostly because I changed my mind halfway through the coding and didnt think to change class names. It might be confusing to an examiner to see a simple bullet note rejecting the adapter pattern and then see an interface called DBAdapter or something similar.
Im going to try to let the code do the talking so to speak. Actually I already did in many ways. I actually used class names Model, View and Controller a the three classes in my gui package. I guess as long as the code is commented and I give the bullet point justifications as to why i used MVC, there is little point telling the examiner than the Model class represents ... ooohhh let me see if I can rememeber .... yeah, the model part of that pattern.
So I am actually way happier now. Im still gonna include a more verbose programmers text, but im not going to put much into it, just a description of the major classes in each package and how some of the more important 'bits' work.
Thanks, for all the input. I actually think this is the worst part of the exam
 
George Marinkovich
Ranch Hand
Posts: 619
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi Morgan,

Originally posted by Morgan Bath:

So I am actually way happier now. Im still gonna include a more verbose programmers text, but im not going to put much into it, just a description of the major classes in each package and how some of the more important 'bits' work.


Instead of a programmers text you could put the same sort of information into your javadoc documentation (which is a required element of the project, unlike a separate programmer's guide). The "description of the major classes in each package and how some of the more important 'bits' work," can be placed into an html file named package.html along with the java source code in each package directory. You can also describe the package structure in a file named overview.html. The package.html files will be picked up automatically by the javadoc tool, but you will have to use the -overview switch to get the javadoc tool to include your overview.html file in your generated javadoc documentation.
Hope this helps,
George
 
Morgan Bath
Ranch Hand
Posts: 196
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Like it. Im gonna have a readme.txt with a list of files, and I can mention this in the Javadoc section. Thanks
 
reply
    Bookmark Topic Watch Topic
  • New Topic