-
Notifications
You must be signed in to change notification settings - Fork 0
Open
Labels
discussThe issue is scheduled for internal discussionThe issue is scheduled for internal discussiondocumentationImprovements or additions to documentationImprovements or additions to documentation
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:
TODOs are formatted differently, making them harder to search and manage. - Lost Context: Important information about why a
TODOexists or who created it can be missing. - Stale
TODOs: Without clear guidelines and review processes,TODOs 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.,
TODOfor planned work,FIXMEfor known bugs. - Establishing a process for reviewing and resolving
TODOs.
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
TODOs. - 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
TODOs in a tree view) - TODO Highlight Extension (For making
TODOs more visible)
- Todo Tree Extension (Popular for displaying
Discussion Points
- What specific format should we adopt for
TODOcomments? - Which tags (e.g.,
TODO,FIXME,HACK,REVIEW) should we standardize? - How should we integrate
TODOs with our issue tracking system (if at all)? - What should our process be for reviewing and resolving old
TODOs?
Please share your thoughts, suggestions, and any concerns.
paodb and javier-godoy
Metadata
Metadata
Assignees
Labels
discussThe issue is scheduled for internal discussionThe issue is scheduled for internal discussiondocumentationImprovements or additions to documentationImprovements or additions to documentation
Type
Projects
Status
Inbox (needs triage)