Skip to content

Standardize TODO Comment Conventions #54

@ngonzalezpazFC

Description

@ngonzalezpazFC

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 TODO exists 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:

  1. Standardizing the format: For example, // TODO(username OR Jira-GitHub-Ticket): Clear description of the task.
  2. Defining when to use specific tags: e.g., TODO for planned work, FIXME for known bugs.
  3. 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:

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 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.

Metadata

Metadata

Assignees

No one assigned

    Labels

    discussThe issue is scheduled for internal discussiondocumentationImprovements or additions to documentation

    Projects

    Status

    Inbox (needs triage)

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions