Effective Commenting

When to use

• Explaining complex business logic or algorithms.

• Documenting public APIs (Data layer → Domain layer).

• Clarifying non-obvious workarounds, hacks, or side effects.

• Warning about potential pitfalls or future refactoring needs.

Steps

• Assess Necessity: Review if the code can explain itself; if so, proceed without comments. Only comment if the code cannot convey the full context.

• Clarify via Naming: Rename methods and variables to describe their purpose explicitly.

• Document Intent: Write comments that explain the "why" (business context, constraints) behind the implementation.

• Finalize Output: Ensure only the active, necessary code remains, removing any temporary artifacts or disabled blocks.

• Distinguish Scope: Use /// for public API documentation and // for internal implementation notes.

Code

Bad Examples (Avoid)

// Step 1: Initialize list of users // This variable stores user data final users = <User>[];

// Loop through users to save them for (var u in users) { // validation logic if (u.isValid) { save(u); // AI thought: saving to database here } }

// Code below is deprecated // void oldFunction() { // print('old logic'); // }

Good Examples

/// Syncs user data with remote backend. /// /// Throws [SyncException] if network fails or data is invalid. Future<void> syncUser() async { // Use a LinkedHashMap to preserve insertion order for UI rendering, // as the backend returns unordered JSON but order matters here. final cache = <String, User>{};

try { await _api.fetch(); } catch (e) { // Suppress 404 errors as they indicate "no data yet" for this specific // endpoint, which is a valid state for new users. if (e is NetworkException && e.statusCode == 404) return; rethrow; } }

/// Example of self-explanatory code (No comments needed) bool get isAdult => age >= 18;