Working Draft
A specification for enhancing TODO messages with emojis for easier comprehension and organization.
| Package | IDE | Description | Status |
|---|---|---|---|
| Snippets Extension | Visual Studio Code | Snippets to generate the TODO Convention | In Progress, Alpha |
The TODO NUKEM specification is a lightweight convention applied to TODO comment messages. It offers straightforward guidelines for crafting feature-rich comments, facilitating the development of automated tools. Designed for rapid visual comprehension of tasks, this convention may enhances efficiency in coding.
The comment message should be structured as follows:
// TODO: <classification> <description> [optional meta]
// TODO: 🟩 ✨ 🛠️ Gear up and get ready to "Hail to the king, baby!" as I kick some alien behind
// TODO: 🔶 🐛 🔄️ It's time to chew bubble gum and kick ass, and I'm all outta gum
This block is used to indicate the priority of a task. It uses three different emojis to represent low (🟩), medium (🔶), and high (🔴) priority levels.
Instead of using the same shape like 🟩 🟨 🟥, we pick 🟩 🔶 🔴 with different shapes so that the distinctions are not solely based on the colors red and green, especially considering color blindness.
| Emoji | Text | State | Desc |
|---|---|---|---|
| 🟩 | Prio.Low | Normal | Default |
| 🔶 | Prio.Medium | Middle | |
| 🔴 | Prio.High | High |
This block is used to specify the type of task. It uses two emojis to represent a feature (✨) and a fix (🐛).
| Emoji | Text | State | Desc |
|---|---|---|---|
| ✨ | Type.Feature | Feature | Default |
| 🐛 | Type.Fix | Fix/Bug |
This block is used to provide context for the task. It uses a variety of emojis to represent different contexts such as design (🎨), documentation (📝), testing (🧪), performance (🚀), language (🌐), security (🛡), update (🔄), optimization (🛠), and review (👀).
| Emoji | Text | State | Desc |
|---|---|---|---|
| 🎨 | Context.Design | Design | |
| 📝 | Context.Doc | Documentation | |
| 🧪 | Context.Test | Test | |
| 🚀 | Context.Perf | Performance | |
| 🌐 | Context.Lang | Language | |
| 🛡 | Context.Sec | Security | |
| 🔄 | Context.Update | Update | |
| 🛠 | Context.Optimize | Optimize | |
| 👀 | Context.Review | Review |
We are in an early testing phase so this block is still incomplete.
We are happy to receive feedback on this.
| Type | Example | Desc |
|---|---|---|
| To Be Discussed (TBD) | [💬 TBD] | This block is used when a task needs further discussion. It is represented by the 💬 emoji. |
| Scope | [🎯 ThisComponent] | This block is used to specify the scope of a task. It is represented by the 🎯 emoji. |
| Ticket | [🎫 TDN-123] [🎫 TDN#123] |
This block is used to link a task to a specific ticket. It is represented by the 🎫 emoji. |
| Until | [📅 2025-Q1] | This block is used to specify a deadline for a task. It is represented by the 📅 emoji. |
| Assignee | [👤 Assignee.Name] | This block is used to assign a task to a specific person. It is represented by the 👤 emoji. |
| Author | [✍️ Author.Name] | This block is used to indicate the author of a task. It is represented by the ✍️ emoji. |
| Version | [🔖 v1] | This block is used to specify the version of a task. It is represented by the 🔖 emoji. |
| Docs | [📚 Docs] | This block is used to indicate that a task is related to documentation. It is represented by the 📚 emoji. |
| Block-Commit | [🛑 Block-Commit] | This block is used to prevent a commit if this Block is set. It is represented by the 🛑 emoji. This only works with additional configuration for Git hooks tools and does not work out of the box. |
Are you missing an important emoji? Then take a look at the Contribution Guidelines and create a new issue or pull request.
| 📦 | Context.Package | Package |
e.g.
| ⬛ | Prio.Unknown | Unknown |
Why Use this Comment Convention
- quick visual capture of the task
- Later possible filtering of tasks by areas
- Meta information
The following is just a demo of what filtering could look like functionally in the future:
You see here an old state of the prio emojis.
Why do you use the choice between bug and feature as the second information in the classification block and not simply TODO and FIXME?
The developers surveyed so far said they rarely use FIXME. We have therefore currently decided to have the most comprehensive convention possible. In the future, we plan to make this adjustable per project. Therefore, this is only the default case.
What is the difference between the review and the TBD emoji?
Review is when the category is not yet available. TBD is more likely to be additional when the category is already clear. But this may change in the future version.
How did you choose the emojis?
We compared many emojis and ensured that they were similar in size. These were then shown to a few developers to make a general selection. For example, the green and red emoji are not ideal for people with red/green weakness. We are therefore already working on a setting option at project level. Here you could then choose between emoji-only, text-only and or text-emoji combination for each project. But this is an option for the future.
For more questions and answers, please visit our Q&A Discussions.
The specification builds on existing TODO messages.
After the "TODO:" there is a space and then the first block.
The classification block contains exactly 3 emojis. These are separated from each other by a space.
This is followed by the message as usual.
The meta block follows the message. This is optional. Here a unit of the block begins with square brackets. Within the square brackets you start with the appropriate emoji followed by a space and the associated text. A space is placed after the closed bracket if another unit follows. Of course, there doesn't have to be a space at the end.
The language is English. This also applies to the date or quarter format.
- Surveys and data are currently being collected
- Add integrations (linter, generator, report ...)
- Testing and feedback
For those who want to use this convention only in dev branches and not in main/production, we are planning to build guards that prevent comments from being merged into main. e.g. like GitHub(...) actions or git hooks.
A text only, and text-emoji combination variant is planned as an alternative to the emojis only mode.
e.g. like:
[🟩-low][✨-feat][🧪️-test]
The plan is for this to depend on the project configuration in the project configuration file, for example it could be called todonukem.json or commentsconvention.json (with or without trailing dot for the filename) for a general naming. But that's just an idea so far and not part of this version.
At some point, it would also be great if, as discussed in step 2, we could have not only a project-level config but also a user-level config that can override the default and project config. For example, if a user prefers a different config than the rest, we could use text-only as a basis by default, and then through our future extensions, provide a different visual variant without changing the code.
If you find this project helpful, please consider giving it a star on GitHub.
We do not currently offer direct support for this project.
We appreciate the support from Eviden, helping us continue our open source work.
See the LICENSE file for details.
Please note that this project, TODO NUKEM, is not officially associated with or endorsed by the Duke Nukem franchise or its creators. It is an independent project developed by the open-source community and does not claim any rights to the Duke Nukem trademark or any related materials.
Thanks goes to these wonderful people (emoji key):
 Jochen Simon 🤔 🎨 💻 |
 Julian Kasimir 🤔 🎨 💻 |
 Noah Duerkes 👀 |
This project follows the all-contributors specification. Contributions of any kind welcome!