The %todo
directive provides a formal way to flag parts
of your code that need future attention. It improves productivity by
making tasks easy to track without disrupting the flow of development.
At compile-time, %todo
produces a soft warning that
does not stop compilation but lists the issue, making it clickable in
the development environment for fast navigation.
Syntax
%todo developer_name description_text
-
developer_name (required): A name or initials of who is
responsible.
-
description_text (required): Brief description of the task or
reminder.
Example
%todo SSue Improve performance of this loop since it is a "hot spot"
Elements of Good %todo
Text
Writing useful %todo
entries makes your notes actionable and
easy to revisit. A good entry should contain:
- Clear intent: State exactly what needs to be done or reviewed.
- Specific context: Mention what part of the code or behavior is affected.
- Actionable phrasing: Use verbs like “fix,” “refactor,” “remove,” “investigate,” or “optimize.”
- Avoid vagueness: Don’t write "fix this"—say what needs fixing.
- Be concise: One line is ideal, especially for the hover preview in editors.
Good Examples
%todo JD Refactor this loop to reduce memory usage
%todo AL Investigate why login fails on invalid tokens
%todo MP Optimize sort algorithm for large datasets
Weak Examples
%todo JD Fix
%todo AL ???
%todo MP Look at this
Behavior
- Compilation will continue normally.
-
A soft warning message will be generated, showing the developer name SSue
and the text.
-
In the SPDEV and/or Visual Studio Code editors, the %todo warning is
clickable, allowing fast jumping to the relevant line of code.
%TODO Summary:
- Bridges Code and Project Management: Creates a
formal, visible system for tracking technical debt and pending
work that generates compile-time warnings managers can see
without reading code.
- Enforces Accountability: Required developer
names ensure clear ownership of tasks, preventing the "anonymous
TODO problem" that plagues most codebases.
- Prevents Technical Debt Amnesia: Critical
issues can't be lost in comment noise or forgotten—they remain
visible until addressed, making invisible problems
actionable.
- Preserves Context and Knowledge: Important
decisions and requirements stay embedded in the code itself,
creating an audit trail that survives team changes and project
transitions.
- Scales with Enterprise Needs: Particularly
valuable for regulated industries, large teams, and long-term
projects where compliance, coordination, and knowledge
preservation are critical.