Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

About choices.txt

 
Chih-Wei Lee
Ranch Hand
Posts: 129
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I am at the point to work on documentation but I have no idea how much I am supposed to write in choices.txt.
I read some post on JavaRanch and found someone has below bulletin.
I just wonder if this is too much?
Why I need to talk about code clarity and documentation in choices.txt?
According to the insturction, choices.txt is

"Detail the problems you perceived, the issues surrounding them, your value judgments, and the decisions that you made. This document should also describe any uncertainties you had regarding the project, and the decisions you made when resolving them."

So I consider it's a document to describe your decision about design.
It's not a document to talk about the design concept.

Is this correct?
what do most people do about choices.txt?

1]Overview.
2]Server Design.
3]Client Design.
4]Record Locking implementation.
5]Record Search implementation.
6]RMI vs Sockets based Remote Server implementation.
7]Modification vs Extension of Data class.
8]DefaultTableModel vs Extending AbstractTableModel.
9)Generic Client vs Generic Server.
10]Use of standard design patterns.
11]Exception handling scenarios.
12]Thread Safety.
13]Flexibilty for extension in future implementations.
14]Code clarity.
15]Class and its members naming convention and use of intuitive field names.
16]Documentation.
17]Final Packaging for submission.
 
mohamed sulibi
Ranch Hand
Posts: 169
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
hiz;

also i don't start writing the choices.txt file; but when i will writing i will doing the following:

1- introduction about this file.
2- package structure.
3- issues in the db package
4- issues in the data class.
5- using decorator pattern to decorate the decoratee data class to more meaningful DataService class.
6- using adapter pattern to adapt the adaptee DataService class to use in the network mode instead of local mode.
7- issues in the server design, ( rmi or pure socket connection).
8- client interface design ( GUI , MVC, ... ).
9- general consideration ( exception handling, feature i don't provide, ...).


what you think about my choices.txt structure ?

Regards.
Mohamed darim.
 
Chih-Wei Lee
Ranch Hand
Posts: 129
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Mohamed
Most of them make sense, but for 2 and 9
What you want to document the package structure in choices.txt?
What's your concern?
Also is this a document to describe your design concept?
even there is nothing about decision, just you prefer to do so.

Thanks

Lee
 
mohamed sulibi
Ranch Hand
Posts: 169
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
hiz;

What you want to document the package structure in choices.txt?


i mean the package i used to group the classes in the project, (i.e in my
project i use 5 package ) and why i use this 5.

Regards.
Mohamed Darim.
 
Chih-Wei Lee
Ranch Hand
Posts: 129
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
So I just want to clarify if
this is a document you can describe your design concept.
Not only about those issues you have to make a decision.

Is this correct?

Thanks

Lee
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic