Part 3

Learning Goals

By the end of this part, you should be able to:

1. Explain the five dimensions of ACCEU
2. Evaluate whether documentation adheres to the principles of ACCEU
3. Annotate code with comments that are accurate, clear, complete, easy-to-use, and up-to-date

Learn: Components of ACCEU

Part 3 Slides (pdf)

In the video above, there are references to this piece of code by Java's developers: ArrayList.java. If you want to see the code for yourself in its entirety, see this GitHub page

Practice: Working with ACCEU

Coming Soon... still porting this over from the LMS!

Apply: Annotate!

Overview

In this hands-on activity, you will apply the ACCEU framework by creating good documentation for a real Java file. You will evaluate and improve the file’s documentation to make it accurate, clear, complete, easy-to-use, and up-to-date.

The Scenario

Imagine you are working in a GitHub repository for a user login system project. Before submitting a pull request to your team, you must ensure that your file is well-documented and adheres to ACCEU principles.

The Challenge

1. Download the SignupInteractor.java file from the CAUserLogin repository:
   
2. Open the Java file in your IDE. Imagine this is the code you just completed as part of the project scenario.
3. Use the ACCEU framework to document the code. Add:
   • Meaningful comments
   • Function headers
   • A program header (file-level documentation)
   If helpful, refer to the provided checklist as a guide.
4. Reflect on your experience:
   • What challenges did you encounter when writing high‑quality source code documentation?
   • Which aspects of ACCEU were easiest or hardest to apply?

If you are struggling or have any questions about these steps, feel free to ask!

Go to Part 4

Optional readings and references:

• "M" reading: https://medium.com/@kevinteaches/9-tips-for-updating-documentation-ac1749a2aa1b
• "Novikova" reading: https://blog.jetbrains.com/writerside/2022/01/the-holy-grail-of-always-up-to-date-documentation/
• "Savonen" reading: https://jhudatascience.org/Documentation_and_Usability/how-to-keep-your-documentation-up-to-date.html
• "Veerman" reading: https://madewithlove.com/blog/pragmatic-ways-of-keeping-documentation-up-to-date/