Copyright © 2009 - 2010 Christian Hujer and Ralf Holly, All Rights Reserved.
This specification describes a standardized format for TODO comments in source code or other textual information. TODO comments are a wide-spread form for documenting open issues and potential for improvement in source code and other technical documents. Its goal is to improve the communication, filtering and tracing of such issues.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current Riedquat publications and the latest revision of this technical report can be found in the ↗Riedquat technical reports index at http://www.riedquat.de/TR/.
This document is a working draft. It is published to the hacker, internet and software development communities as a request for comments. Please send your comments to <✉cher@riedquat.de>.
This document specifies a syntax for TODO comments. TODO comments are a wide-spread form for documenting open issues and potential for improvement in source code and other technical documents. The goal of this specification goal is to improve the communication, filtering and tracing of such issues. The idea for this document was born from reading [TODOORNOT], a BLOG entry by Ralf Holly.
There are multiple dimensions about issues in source code which all need to be addressed somehow:
Either an issue exists or it does not exist. But we can agree, especially when talking about source code, that not being aware of an issue does not necessarily mean that there is no issue. That means we can describe a simplified physical issue lifecycle with the following states:
This specification does not suggest that placing comments into source code always is the most appropriate tool for issue tracking. There are some issues with FIXME comments. A FIXME comment cannot be put in source code for issues for which the location in source code is not yet known.
The editor aims this section especially at customers, evaluators and reviewers of source code.
There is no relationship between the presence or number of TODO comments and any kind of quality or code maturity. It is not recommended to make absence of TODO comments a quality or acceptance requirement.
Of course, code without issues is better than code with issues. For code with issues, known issues are better than unknown issues: To address an issue, it must be known first. For known issues, it is better to know the location of the issue in source code than not to know it.
TODO comments can be of quite different nature, which the following example illustrates.
// FIXME:2009-05-04:Christian Hujer:Possible buffer overflow if length is too small.
// FIXME:2009-05-04:Christian Hujer:Fails for more than 2^16 users.
The first comment indicates a potential security problem.
The second comment indicates a potential future issue. The programmer wished to implement the code in context to handle more than 2^16 users. For some reason he decided not to do so for now, probably because it was not a requirement. The presence of that comment allows any programmer to easily spot potential problems when handling more than 2^16 users.
[1] TodoComment ::= Keyword ':' IsoDate ':' Author ':' Text
The following example illustrates how such a TODO comment could look like independent of a programming language:
TODO:2009-04-27:Christian Hujer:Add an example.
The following example illustrates how such a TODO comment could look like in C, C++, C#, EcmaScript, Java or similar languages.
// TODO:2009-04-27:Christian Hujer:Add an example.
[2] Keyword ::= ('TODO' | 'FIXME' | 'XXX' | 'Review') The keyword for indicating a TODO comment is the most important part. The keyword 'TODO' is the most well known keyword for TODO comments. [SUNJAVACODE] as well as [JARGON] describe two other keywords besides 'TODO': 'FIXME' and 'XXX'. This document proposes another keyword 'Review' which identifies issues found in reviews which do not fit in one of the other categories.
TODOTODO indicates something that needs work.FIXMEFIXME indicates something that is bogus and broken. XXXXXX indicates something that is bogus but works. ReviewReview documents the comments of a code review. [3] IsoDate ::= Digit Digit Digit Digit Digit* '-' Digit Digit '-' Digit Digit
[4] Author ::= Char* - (Char* ':' Char*)
[5] Text ::= Char*
[6] Digit ::= TODO
[7] Char ::= TODO
The syntax can be easily parsed with regular expressions in languages like ECMAScript, Java, Perl or XML technologies (e.g. XML Schema / XPath for XSLT). This chapter describes regular expressions for parsing the described TODO syntax.
The following regular expression can be used to parse TODO comments in ECMAScript.
(TODO|FIXME|XXX|Review):(\d{4,}-\d{2}-\d{2}):([^:]+):(.*)The following regular expression can be used to parse TODO comments in grep.
\(TODO\|FIXME\|XXX\|Review\):\([0-9]\{4,\}-[0-9]\{2\}-[0-9]\{2\}\):\([^:]\+\):\(.*\)The following regular expression can be used to parse TODO comments in grep -E.
(TODO|FIXME|XXX|Review):([0-9]{4,}-[0-9]{2}-[0-9]{2}):([^:]+):(.*)The following regular expression can be used to parse TODO comments in grep -P.
(TODO|FIXME|XXX|Review):(\d{4,}-\d{2}-\d{2}):([^:]+):(.*)The following regular expression can be used to parse TODO comments in Java using java.util.regex.
(TODO|FIXME|XXX|Review):(\d{4,}-\d{2}-\d{2}):([^:]+):(.*)Please note that if you use this regular expression as a String in Java, that the '\'-signs need additional escaping. The following example shows how to use this regular expression in a String.
String re = "(TODO|FIXME|XXX|Review):(\\d{4,}-\\d{2}-\\d{2}):([^:]+):(.*)";The following regular expression can be used to parse TODO comments in Perl.
(TODO|FIXME|XXX|Review):(\d{4,}-\d{2}-\d{2}):([^:]+):(.*)The following regular expression can be used to parse TODO comments in sed.
(TODO|FIXME|XXX|Review):([0-9]{4,}-[0-9]{2}-[0-9]{2}):([^:]+):(.*)The following regular expression can be used to parse TODO comments in vim.
\(TODO\|FIXME\|XXX\|Review\):\(\d\{4,}-\d\{2}-\d\{2}\):\([^:]\+\):\(.*\)The following regular expression can be used to parse TODO comments in XML Schema, XPath and XML Query. It also is suited to construct data types for XML Schema.
(TODO|FIXME|XXX|Review):(\p{Nd}{4,}-\p{Nd}{2}-\p{Nd}{2}):([^:]+):(.*)This chapter lists open issues of this working draft.
[1] TodoComment ::= Keyword ':' IsoDate ':' Author ':' Text
[2] Keyword ::= ('TODO' | 'FIXME' | 'XXX' | 'Review')[3] IsoDate ::= Digit Digit Digit Digit Digit* '-' Digit Digit '-' Digit Digit
[4] Author ::= Char* - (Char* ':' Char*)
[5] Text ::= Char*
[6] Digit ::= TODO
[7] Char ::= TODO
