Open
Description
Currently, our team lacks a standardized approach to using TODO
(and similar) comments (e.g., FIXME
, HACK
) in our codebase. This can lead to:
- Inconsistency:
TODO
s are formatted differently, making them harder to search and manage. - Lost Context: Important information about why a
TODO
exists or who created it can be missing. - Stale
TODO
s: Without clear guidelines and review processes,TODO
s can become outdated and clutter the code. - Inefficient Tracking: Team members might not be aware of all pending tasks or their priority, as IDE task lists might not be uniformly configured.
Proposal
I propose we discuss and adopt a set of conventions for writing and managing TODO
comments. This would involve:
- Standardizing the format: For example,
// TODO(username OR Jira-GitHub-Ticket): Clear description of the task.
- Defining when to use specific tags: e.g.,
TODO
for planned work,FIXME
for known bugs. - Establishing a process for reviewing and resolving
TODO
s.
Benefits
Adopting these conventions will help us:
- Improve Code Clarity: Make it easier to understand pending tasks and their context.
- Enhance Collaboration: Ensure everyone is on the same page regarding outstanding work.
- Increase Maintainability: Keep the codebase cleaner by reducing stale or vague
TODO
s. - Better Utilize IDE Tooling: Allow team members to effectively use the "Task List" or "TODO" features in their respective IDEs.
Resources for IDE Tooling & Style Guides
To facilitate this discussion and ensure our conventions work well with our common IDEs, here are some relevant resources:
-
General Style Guide:
-
Eclipse IDE:
- How to use TODO and FIXME task tags in Eclipse (How to configure
TODO
,FIXME
, etc.)
- How to use TODO and FIXME task tags in Eclipse (How to configure
-
IntelliJ IDEA:
-
Visual Studio Code (via Extensions):
- Todo Tree Extension (Popular for displaying
TODO
s in a tree view) - TODO Highlight Extension (For making
TODO
s more visible)
- Todo Tree Extension (Popular for displaying
Discussion Points
- What specific format should we adopt for
TODO
comments? - Which tags (e.g.,
TODO
,FIXME
,HACK
,REVIEW
) should we standardize? - How should we integrate
TODO
s with our issue tracking system (if at all)? - What should our process be for reviewing and resolving old
TODO
s?
Please share your thoughts, suggestions, and any concerns.
Metadata
Metadata
Assignees
Type
Projects
Status
Inbox (needs triage)