Code Documentation and Comments

Well-chosen names and clear structure reduce the need for comments, but some code inevitably requires explanation. This section guides when and how to add meaningful documentation.

8.1 Self-Documenting Code First

Code should read like prose. Use descriptive variable, method, and class names.
Avoid comments that repeat the code. If the code can be made obvious by renaming or extracting a method, do that instead.
Do not comment out dead code; delete it and rely on version control history.

8.2 When to Write Comments

Non-obvious algorithms or business logic that cannot be simplified.
Workarounds for third-party bugs, framework quirks, or temporary solutions. Include a TODO with a Jira ticket reference (see Section 8.5).
Public API documentation: classes, interfaces, methods, and properties that are consumed by other modules or services must carry proper doc comments.
Magic values that arise from external constraints (e.g., compliance limits, protocol headers) and cannot be extracted as named constants.
Commented regex that benefits from an inline explanation.
Performance-sensitive code where optimization choices might appear counter-intuitive.

8.3 C# Documentation Comments

Use XML documentation comments (///) for all public, protected, and internal types and members.
Include <summary> for the main description. Use <param>, <returns>, and <exception> where applicable.
Keep descriptions concise but complete; mention units, expected ranges, and side effects.
Example:
/// <summary> /// Calculates the total price with applicable tax. /// </summary> /// <param name="subtotal">The pre-tax amount in the order currency.</param> /// <param name="taxPercentage">Tax rate between 0 and 100.</param> /// <returns>The total price including tax.</returns> /// <exception cref="ArgumentOutOfRangeException">Thrown when <paramref name="subtotal"/> is negative.</exception> public decimal CalculateTotal(decimal subtotal, double taxPercentage) { // ... }

8.4 TypeScript Documentation Comments

Use JSDoc syntax (/** ... */) for exported functions, classes, interfaces, and public methods.
Include @param, @returns, @throws, and @example when relevant.
TypeScript types often remove the need for extensive JSDoc, but natural-language explanations remain valuable.
Example:
/** * Transforms an array of raw orders into display-ready items. * @param orders - Raw orders from the API. * @returns Sorted and filtered list of OrderViewModel. */ export function prepareOrders(orders: Order[]): OrderViewModel[] { // ... }

8.5 TODO Comments

TODO comments must carry a Jira ticket reference or other permanent identifier: // TODO: JIRA-1234 – Refactor after API v2 is stable.
Do not leave anonymous TODOs; they become invisible debt.
Periodically review open TODOs during sprint planning or retrospectives.

8.6 Inline Comments

Place inline comments on their own line, or at the end of a line only when very short.
Capitalise the first word, and use proper grammar.
Do not write redundant comments like // increment counter; instead explain why, not what.

8.7 Commit Messages vs Code Comments

Do not use code comments to describe the history of changes (e.g., // Changed by John on 2024-01-01). That information belongs in the version control history (commit messages).

04 мая 2026