• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

B&S: Where to comment design decisions?

 
Darya Akbari
Ranch Hand
Posts: 1855
  • Mark post as helpful
  • send pies
  • 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
 
John Smith
Ranch Hand
Posts: 2937
  • Mark post as helpful
  • send pies
  • 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
  • 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
  • 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
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic