Skip to content

TODO comments

Jump to bottom
Alexander Yevsyukov edited this page Jun 20, 2025 · 2 revisions

Usage

TODO comments are allowed for code that is temporary, a short-term solution, or good-enough but not perfect.

You need to have a really good reason to check-in your code into VCS with TODO comments left.

Format

The following pattern should be used for TODO comments:

// TODO:$date:$contributor: $comment

Where:

  • $date — is the local date in ISO 8601 ‘extended’ format.

  • $contributor — is the person or agent who left the comment.

    This is NOT for whom the comment is addressed. We assume that comments are addressed to the whole development team.

Please notice the space character after the last colon. This space character is needed for reader's convenience.

Example:

// TODO:2011-01-26:alexander.yevsyukov: Remove the method below and this comment after February 1st, 2011.

Marking a TODO block

If you need to make obvious that your TODO comment applies to a certain block of code, use the following format:

// TODO:END

Referencing future events

If your TODO comment refers to an event in the future be sure to specify the moment precisely:

  1. By giving a date: Fix this logic by February 1, 2032., or
  2. By specifying event conditions: Remove this code after we migrate to new protocol V3.

Live template for IntelliJ IDEA

To create a live template for the todo comments, please perform the following steps:

  1. Go to Preferences -> Live Templates.

  2. Create a new template with the Abbreviation "todo"

  3. Put this text for the template: $LINE_COMMENT$ TODO:$DATE$:$NAME$: $END$

  4. Press on the "Edit Variables" button.

  5. For the $LINE_COMMENT$ variable:

  • Select the following function in the Expression column or simply paste it as text: lineCommentStart()

  • Check "Skip if defined".

  • This var will be evaluated to a line comment which is used in the language of context (e.g. // or #)

  1. For the $DATE$ variable:

  • Enter the following code in the Expression column: date("yyyy-MM-dd")

  • Check "Skip if defined"

  1. For the $NAME$ variable:

  • Enter your GitHub ID.

  • Check "Skip if defined"

Bonus track: grep commands related to TODO comments

  • Sorting all TODOs by date:

    grep -R TODO: * | sort

  • Building a list of TODO owners:

grep -oRE "TODO:[^:]+:([^:]+)" * | sed -e "s/^.*://" | sort | uniq -c
  • This grep command will catch most ill-formed TODOs:
grep -iRE "todo|fixme|bugbug|???" * | grep -vP "TODO:d{4}-d{2}-d{2}:.{3,}:.{10,}"

Clone this wiki locally