Code Documentation Guidelines

Code Documentation Guidelines

Use these guidelines when documenting code in a file.

Documentation is not mandatory. But when a class or function is documented, it must follow the KDoc conventions described below.

1. When to document

Checklist:

• The code is not self-explanatory (complex logic, non-obvious behavior, side effects).
• The class or function is part of a public or shared API used by other parts of the project.
• There are constraints the caller must know (valid ranges, thread-safety, exceptions thrown).

Why?

Good documentation helps teammates understand what a piece of code does and why it exists, without having to read the implementation.

When not to document

• The name already says everything (e.g. fun getUserName(): String).
• The comment would only repeat the code.
• Private helpers with obvious behavior.

Prefer clear names over comments. Documentation should add information, not noise.

2. KDoc format

Checklist:

• The comment starts with /** and ends with */.
• The comment is placed directly above the declaration it documents.
• The first sentence is a short summary of what the element does.
• A blank line separates the summary from the detailed description.
• Block tags (@param, @return, ...) come after the description.

Example:

/**
 * Calculates the total price of a trip.
 *
 * The total includes transport, accommodation and activities,
 * but excludes optional insurance.
 *
 * @param trip the trip to calculate the price for.
 * @param currency the currency used for the result.
 * @return the total price, rounded to two decimals.
 * @throws IllegalArgumentException if the trip has no participants.
 */
fun calculateTotalPrice(trip: Trip, currency: Currency): Double

Writing style

• Write in English.
• Use the third person for the summary: "Calculates...", "Returns...", not "Calculate..." or "This function calculates...".
• Keep the summary to one sentence.
• Describe behavior and intent, not implementation details.
• Use Markdown for formatting (code, bold, lists) when it improves readability.

3. Documenting classes

Checklist:

• The summary explains the responsibility of the class.
• Properties of the primary constructor are documented with @property.
• Constructor parameters that are not properties are documented with @param.

Example:

/**
 * Represents a vote cast by a user on a shared trip.
 *
 * A user can vote only once per trip; a new vote replaces the previous one.
 *
 * @property userId the identifier of the user who voted.
 * @property tripId the identifier of the trip being voted on.
 * @property score the score given, between 1 and 5.
 */
data class TripVote(
    val userId: String,
    val tripId: String,
    val score: Int
)

4. Documenting functions

Checklist:

• Every parameter is documented with @param.
• The return value is documented with @return (omit it for Unit).
• Exceptions that can be thrown are documented with @throws.
• For extension functions, the receiver is documented with @receiver if useful.

Example:

/**
 * Formats the date for display in the trip overview.
 *
 * @receiver the date to format.
 * @return the date formatted as `dd.MM.yyyy`.
 */
fun LocalDate.toDisplayString(): String

5. Common KDoc tags

Tag	Use for
@param <name>	A function parameter or constructor parameter
@property <name>	A property declared in the primary constructor
@return	The value returned by a function
@throws <Exception>	An exception the function can throw
@receiver	The receiver of an extension function
@constructor	The primary constructor of a class
@see <element>	A related class or function
@sample <function>	A function showing example usage

Linking to other elements

Use square brackets to link to another class, function or parameter:

/**
 * Adds the [TripVote] to the trip and updates [Trip.averageScore].
 */

6. When is the documentation ready?

• It follows the KDoc format.
• The summary is a single, clear sentence.
• All parameters, properties, return values and exceptions are documented.
• It describes what the code does and why, not how.
• It is up to date with the code (no outdated parameters or behavior).
• It contains no spelling mistakes or commented-out code.

7. Keeping documentation up to date

Checklist when modifying documented code:

• The summary still matches the behavior.
• Added, removed or renamed parameters are reflected in the tags.
• New exceptions are documented with @throws.

Outdated documentation is worse than no documentation: update it in the same commit as the code change.