• 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

B&S: Where to comment design decisions?

 
Ranch Hand
Posts: 1855
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi all,

concerning a must in my assignment:

Design decisions must be described briefly but clearly in your comments



I wonder where to put these comments. When I stick to the word comments in my assignment than it seems to be in my source code.

But something tracks me to choices.txt

Where do you describe it?

Regards,
Darya
 
Ranch Hand
Posts: 2937
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Well, there are actually three places where you would put your explanations.

1. Java Docs: describe your class interfaces as well as public method documentation. That would be for the class users that do not need or do not have access to the source code.

2. Comments inside the code: this is for your fellow programmers who would be maintaining your code. If you think they may have trouble understanding what your code does and why, add your comments.

3. DesignChoices.txt: that's a 3 to 10 pages document just for the grader. In there, you would describe your design decisions fully.

You may also have a requirement for the user documentation. That would be the fourth place. In there, you would just describe the purpose of the program and how to use it fro the end user point of view.
 
Darya Akbari
Ranch Hand
Posts: 1855
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi John

at first I would think that this is all redundant info, but from the user's point of view I aggree with you.

Thanks,
Darya
 
Darya Akbari
Ranch Hand
Posts: 1855
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Hi,

I read John's response again and have now doubts whether he means comments in general.

I would like to know what other thinks. Do we really need to put all design decision comments into all kind of documents John listed above

Any hints are welcome

Regards,
Darya
 
reply
    Bookmark Topic Watch Topic
  • New Topic