|
C.2 %TODO -- Managing Future Improvements |
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.
|
Hide Description
|
|
|
Enter or modify the code below, and then click on RUN |
|
Looking for the full power of Sheerpower?
Check out the Sheerpower website. Free to download. Free to use. |
