The Method Named doMagic()
It was a Tuesday. I opened a project I hadn't touched in four months. My goal was to fix a simple bug — something I expected to take twenty minutes.
Instead I found a method named doMagic().
I stared at it. Why is it async? Why does it mutate context and a global variable called spookyGhost? I checked for comments. There were none. Not even a half-hearted TODO.
Past me had written this code. Present me had no idea what it did.
That's the thing about code documentation — you don't feel the need for it until you desperately need it and it isn't there.
Clean Code Isn't the Same as Understandable Code
Most developers, when pushed on this topic, will say: "I write clean code. It's self-documenting."
Here's a quick test of that:
final thing = getThing(userId, true);
What's thing? What does true mean in this context? What does getThing actually retrieve?
If you can't answer those questions from the call site alone, the code isn't self-documenting — it just looks clean. Clean code tells you how something works. Documentation tells you why it exists and when to use it. You need both.
Dart Doc Basics
Dart uses /// for documentation comments. These aren't just for humans — DartDoc and IDEs parse them, and the output shows up in hover tooltips, generated API docs, and code completion.
Widget getThing(String userId, bool fallbackToDefault) { ... }
That getThing call makes sense now. The method name hasn't changed, but the context around it has.
One feature worth using: wrapping identifiers in square brackets creates cross-references in generated docs.
When rendered, [userId] becomes a link to its definition. It's a small touch that pays off when navigating a larger codebase.
What to Document and What to Skip
The most common mistake developers make with documentation is writing it for the wrong things. Documenting obvious one-liners creates noise. Not documenting complex logic creates confusion.
Document when:
- The function or class is public and used across multiple files
- You used a workaround that isn't immediately obvious from reading the code
- The function has non-obvious behavior: side effects, ordering requirements, threading constraints
- A parameter name isn't self-explanatory — especially boolean flags
Skip documentation when:
- The code is a simple one-liner with a descriptive name
- The function is private and used in only one place
- The code is temporary or about to be deleted
A Documentation Structure That Works
The most useful docs follow a consistent structure: what it does, when to use it, and an example. Three layers, and you can read as much or as little as you need.
class ProfileCard extends StatelessWidget {
final User user;
final VoidCallback? onActionPressed;
// ...
}
```
The first line answers "what does this do?" The middle lines answer "when and why would I use this?" The example shows actual usage. Someone new to the codebase can read just the first line and move on, or dig into the details if they need them.
Useful Things Most Developers Don't Know About Dart Docs
Markdown works inside ///. You can use *italic*, **bold**, bullet lists, and fenced code blocks. Docs don't have to be plain text.
You can reference parameters inline. [paramName] in brackets links to the parameter definition in IDEs that support it.
See also: sections are useful. If your method is closely related to another method or class, noting that explicitly saves readers from having to search.
/// {@macro myMacro} lets you reuse documentation across similar widgets or functions without copying and pasting. Useful for widget families that share common behavior.
The return value deserves a line. If a function returns something non-obvious — a nullable type, an empty list on failure, a transformed version of the input — say so explicitly.
The Practical Test
Ask a teammate to explain a method you wrote three months ago, without looking at anything other than the call site. If they can't do it in thirty seconds, you needed documentation.
This isn't about being thorough for the sake of it. It's about the fact that the person who will most benefit from your documentation is often you, six months later, at 11pm, debugging something that should have been obvious.
A Simple Daily Habit
You don't need to document your entire codebase in one sitting. That's overwhelming and it won't happen.
A more realistic approach: pick one undocumented function each day. Write three lines about what it does, when to use it, and any edge cases worth knowing. After a month, you'll have documented thirty functions, and the habit will feel automatic.
Summary
Use /// for Dart doc comments. Wrap identifiers in square brackets to create cross-references. Structure your docs in three layers: what it does, when to use it, and an example. Return value behavior and non-obvious side effects deserve explicit mention. And write docs like you're writing a note to yourself on a bad day — because at some point, that's exactly what they'll be.
The real magic was never in doMagic(). It was knowing what doMagic() was supposed to do.
