Documentation Debate
Prepare
- Read Simple guide to comments.
- Read Comments are more important than code.
- Review Unstable layout in our Java Style Guide.
- Scan How To Write Unmaintainable Code.
- Research the utility and importance of documenting code.
Share
Share the useful and interesting results of your research in the Research yyyy-mm discussion topic of our wiki’s Java Documentation Debate page. Make your posts even more helpful by describing why you made your recommendations—and by sharing your informed opinions of the recommendations of others.
Debate
Our motion is Be it resolved that comments are more important than code.
Agree amongst yourselves as to who will:
- moderate the debate
- conduct pre- and post-polling of the audience
- argue pro (two students)
- argue con (two students)
- film the debate (three people are required: one for each of the moderator, pro, and con)
- edit and produce the video, and post it on our wiki (five people are required: two each for pro and con, and one to arbitrate)
Reflect
How has your understanding of the utility and importance of code documentation evolved? What changes to your coding practice will you make in order to comply with the requirements of our course? What did you learn from this assignment?
Use these questions as a starting point for your reflection of the issue of code documentation. Post your reflections on our wiki’s Java Documentation Debate page and feel free to offer considered observations on the postings of others.
Image credits
Documentation makes you strong: The Most Important Code Isn’t Code, <http://zachholman.com/posts/documentation/>. Retrieved 2014-08-29.
touque.ca > Education Commons > Java > Assignments > Documentation
[This page last updated 2020-12-23 at 12h12 Toronto local time.]
© 2007–2025 Hersch, Bear & Company Limited. All rights reserved. “Grammar Authority,” “grammarauthority.com,” “touque.ca,” and “Canada’s Thinking Cap” are trademarks of Hersch, Bear & Company Limited. All other trademarks and copyrights are the property of their respective owners.
Privacy Policy | Licence to Copy | How to cite | Contact us
