Developer Documentation
Salary
This task pays a fixed salary of 12 MVP points, plus up to 18 quality points for exceeding the minimum requirements — for a total of 30 points, with a maximum of 5 points per person.
Background¶
This section guide you to some additional material that will help you understand the task better. It is not mandatory to read it, but it can be useful for your team.
Minimum Viable Product (MVP)¶
Produce developer-facing notes that help a new teammate understand and use your code. Minimum: add at least one code comment (internal explanation for maintainers) and at least one doc comment (external usage guide for a function/class/module). Then create a short Developer Guide page under docs/dev (Markdown or simple HTML) that: (1) gives a 3–5 sentence overview of the code structure, and (2) links to the exact place in the source where your new comments live (GitLab permalink to file/line). Add a visible link to this guide from the project README.md.
Example: Team 'ByteBusters' make dev info discoverable
They add a code comment above a tricky CSV parsing loop explaining the reason for skipping the header, and a docstring for search_books(query) describing inputs/outputs. In docs/dev, they write a short overview and include “See parsing logic → link to line 74” and “Public API: search_books → link to function.”
Technical Details¶
Code comments (internal) explain why the code is written a certain way (assumptions, invariants, edge cases). Keep them short, near the logic they clarify, and avoid restating the obvious. Python: # … for inline blocks. Java: // … or /* … */ for multi-line notes. Include hints like “preconditions,” “what can go wrong,” or “performance trade-off.”
Doc comments (external) explain how to use a unit: what it does, parameters, returns, and possible errors. Python: put a docstring right under the function/class with a one-line summary, then sections like Args, Returns, Raises, and a tiny usage example. Java: use Javadoc /** … */ with a summary sentence plus @param, @return, @throws. Prefer simple language and copy-pastable examples that actually run.
To extend documentation, add more pages under docs/dev for specific topics (e.g., “Data Format,” “Module Overview,” “How to Run Tests”). Link pages together with permanent links and to source files/lines for key functions. After any refactor, quickly check that links and examples still work.
Quality¶
High-quality developer docs are accurate, concise, and useful for onboarding. Aim for comments that reduce confusion (especially around I/O, error handling, and boundaries between modules) and a guide that lets a newcomer run the project, find the main entry points, and modify one feature safely. Use consistent terminology, proofread, and keep examples minimal but real. Prefer updating or removing outdated comments over leaving contradictions in the code; the best comment tells the intent that code alone can’t.
Example: Team 'PixelPenguins' write for future teammates
They add a docstring to step(grid) describing the grid format and return value, plus a code comment explaining the edge-cell rule. Their docs/dev page lists “Entry points: main.py → menu() → feature functions,” links to those lines, and notes a quick test command. A new teammate can contribute within an hour.