Forums Register Login

B&S: Where to comment design decisions?

+Pie Number of slices to send: Send
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
+Pie Number of slices to send: Send
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.
+Pie Number of slices to send: Send
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
+Pie Number of slices to send: Send
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
The longest recorded flight time of a chicken is 13 seconds. But that was done without this tiny ad:
a bit of art, as a gift, the permaculture playing cards
https://gardener-gift.com


reply
reply
This thread has been viewed 544 times.
Similar Threads
Just got my result 145/155
My locking approach
B&S: What types do you comment with javadoc?
Sharing my Experience SCEA Part II and III
Format for Design Documentation
More...

All times above are in ranch (not your local) time.
The current ranch time is
Mar 28, 2024 11:14:58.