§-Quick questions
NSWSoftware EngineeringModule 4: Software Engineering Project
Quick questions on Documentation practices explained: HSC Software Engineering Module 4
8short Q&A pairs drawn directly from our worked dot-point answer. For full context and worked exam questions, read the parent dot-point page.
What is a good README?Show answer
The README is the front door of the project. A minimum:
What are design documents?Show answer
For non-trivial changes, write a design document before coding. Standard sections:
What are code comments?Show answer
Default to writing no comments. A well-named function, variable and class makes the code self-explanatory.
What is user documentation?Show answer
For end users (not developers):
What is documentation as code?Show answer
Treat documentation like code: in source control, reviewed in pull requests, kept up to date with the code it describes. The diagram below shows where documentation sits in a healthy pull-request pipeline, and where it is skipped when documentation quietly rots.
What is auto-generated dump masquerading as documentation?Show answer
A long file of class signatures is not documentation. Real documentation explains the why and shows examples.
What is code comments restating the code?Show answer
A comment saying "increment counter" next to a one-line counter increment is noise. Comments are for the WHY.
What is documentation in a private wiki?Show answer
If it is not in the repo, it goes out of date. Co-locate documentation with the code it describes.