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

size of choices.txt

 
Uwe Schäfer
Ranch Hand
Posts: 52
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
i�m sure this is a tough question, but how extensively are we supposed to explain our design choices in the choices.txt file ?

per choice, a good 4-liner is ok i guess ?
it is more like i am unsure about what choices are worth to be mentioned in it.

of course some seem ridiculous (... used a LinkedList instead of ArrayList),
some at least questionable questionable (... extracted an Interface for decoupling ...),
some obviously belong there (... used a singlton here to ...)
some mandatory (... my locking stategy uses ...)

any good idea of the borders between them ?

good idea to move choices like the first one code-comments ?
 
Frans Janssen
Ranch Hand
Posts: 357
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Uwe,

of course some seem ridiculous (... used a LinkedList instead of ArrayList),

As you already suggested yourself, I would (in fact: I did) comment such choices in code only.
some at least questionable questionable (... extracted an Interface for decoupling ...),

Common design techniques and patterns don't need a justification at all IMHO.
some obviously belong there (... used a singlton here to ...)

If the pattern is crucial to your solution describe it in choices.txt. Otherwise comment it in the code.
some mandatory (... my locking stategy uses ...)

Obviously this is important!

I divided my choices.txt in two parts: a requirement choices part and a design choices part. In the requirements part I described how I had interpreted ambiguous or conflicting specifications. In the design part I described how I had solved key issues.

For reference, my choices.txt was about six pages long (aimed to keep it shorter, but I felt I could not leave any more out) and I had javadoc comments on all methods (even private ones) and some extra code comments where I felt it was appropriate. I received a 100/100 score for documentation, so I guess that I did not over do it

Frans.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic