Never Forget Anything Before, After and While Coding
Using “codetag” comments as productive reminders
Introduction
Hello there, my name is Eido, I’m a software developer and I want to ask you a question:
Have you ever encountered the moment when you had a super duper idea you wanted to implement while coding that just jumped into your mind?
Guess what? It also happened to me! What are the chances?!
So, you created some sort of nice comment as follows:
// todo implement <super duper idea>This nice comment surely written from several good reasons, such as:
- You didn’t want to give it too much attention.
- You know it’s relevant for another part of your code.
- You assume it should be implemented by itself in another time.
- You didn’t want this “data” to be lost.
The truth is, this happened, happens and will happen to you, to me, and to all programmers while coding, how wonderful!
But there are some elusive problems in using this approach to remember your super duper ideas, what are they?
- There is no term to include this sort of comments (TODO, FIXME, etc.)
- Incomprehensible inconsistent short written comments
- “what-I-was-working-on” time wasted while reading your code either before actually coding or when returning from any break, such as lunch.
Luckily, you came to the right place, and the concept of codetags will solve you those problems:
- From now and on use the term codetag (or plural codetags, you can even codetag it! nice eh?) whenever referring to any sort of these code comments.
- Save you a LOT of “what-I-was-working-on” time waste.
- NEVER forget ANYTHING you are considering, want to do, keep for further implementation, currently working on etc.
It’s time to take action and convene the concept of these kind of comments, which can be found almost in any software project written.
Who are you, “codetag”?
As you probably already understood by reading the introduction, codetag is:
A widely used ad-hoc code comment markup convention to serve as reminder of section of code that need closer inspection or review.
I firstly read about this subject from PEP350 — Codetags which originally written by Micah Elliott in 2005. In this article, we’ll improve it a little for productivity purposes.
How codetags are used?
Codetags can be written in any programming language that supports comments.
I have using them for a while in Java programming language, XML, JavaScript and C#.
I also find them useful while working on multiple projects at the same time (don’t ask me why, but it happened) when I used them as my reminders to what I wanted to do when coming back to a project after a few days (using DOING mnemonic).
How NOT to write a codetag
// fixme <incomprehensible short summary of tech important note>One of the problems in the above codetag is “data” loss — when you read a codetag that wasn’t written accurately enough the following questions start to float around:
What exactly the author meant? who had this weird idea? for god sake how much is it lays here?
Those questions can be really critical because maybe the author of this “codetag” was the developer of this class when it was on early stages, and what he meant is that he thinks that developers of this class should write a technology specific important implementation by code that will prevent a slowdown that most probably will appear in the future, but he didn’t had the the time to do it and there was no slowdown at his time, so he continued, perhaps moved to another project and this part left alone.
How can we avoid this elusive “data” loss?
How to write a codetag
- Write the codetag as if you are writing it to someone that doesn’t have any idea about what you are writing, even if you write it to your own self.
- Use the codetag format as the following section of code (start those lines with your used programming language comment character):
<CODETAG MNEMONIC>: <Codetag subject>
<Optional codetag multi-line message>
<(date)> <Author>Here is an example of a codetag which sticks to above written rules:
/*
* TODO: Change client request from this server
* The login will happen automatically when the service starts up.
* A get service status will be called.
* The methods that he calls will use server responses cache.
* (23/01/2017) Aurobindo Boghos */You probably ask yourself “why the hell should I write those lines and waste my time instead of continue coding faster toward my goal ?”
The answer to this question is divided into two parts:
- By sticking to this format, other teammates and you can easily read and understand it quickly without wasting any time trying to figure out what’s going on and what’s the “poet” intention.
- You don’t waste your time — you can avoid the time to output variable text (such as mnemonic, date, author and priority) that can be scripted by using custom code snippets.
Mnemonics and their purpose
There are numerous mnemonics mentioned in PEP350 — Codetags — Mnemonics, the mnemonics I found the most useful for me are the following:
TODO - something that someone need to do someday (not
necessarily) in the below section of code.DOING - self reminder for what are you currently DOING (not
necessarily) relate to the below section of code.CONSIDER - reminder to CONSIDER some sort of things (not
necessarily) about the below section of code.BUG - the below section of code causes BUG.FIXME - the below section of code need to be FIXed.HACK - the below section of code is a workaround.XXX - important note for you and other programmers (not
necessarily) relate to the below section of code.CLARIFY - very incomprehensible section of code below that you need someone to CLARIFY for you.
Tools
So, you wrote some well-formatted codetags to save both your super duper ideas using snippets and your teammates precious time when they’ll read them, you’d probably want a way to easily manage those codetags so it will be much easier for you and your teammates to organize and navigate back to them, see how many codetags do you have, filter them by their mnemonics etc.
As of today, the following recommended tools are the ones that I’m familiar with, that will provide you the solution to easily manage your codetags:
- Imdone — “…Organizes your codetags in a Kanban board like Trello. It integrates with GitHub issues and leverages TODO.txt syntax for metadata…”, with support to write and nicely display codetags using Markdown markup language, currently available as Atom IDE package (Thanks to Jesse Piascik).
- IntelliJ IDEA TODO— Organize, filter codetags and allow custom codetags syntax, available only as IntelliJ IDEA built-in tool window (including in Android Studio IDE).
You guys are welcome to share more similar tools that you are familiar with and I’d be happy to try and add them to the above list.
The future
Finally, after understanding the concept of codetags, how to save both your own and your teammates super duper ideas, and how manage them, you might already seen that we only use them as reminders.
Currently, I don’t know if there are tools to generate the output of the purposes I’ll mention below, but you might also use them for the following purposes:
- Build your own/team road-map dynamically while writing your code — use the right mnemonics and right tools to create your road-map.
- Issue tracking marker — lays exactly at the issue specific relevant code, so you can modify the codetag format by adding additional fields such as assign to, priority, etc. (cleverly supported by Imdone with its GitHub integration).
- Use your imagination while using codetags and maybe you’ll find them useful for more than just reminders.
Examples
/*
* TODO: Implement Json send via socket
* Also handle the login result
* (29/01/2017) Demeter *//*
* FIXME: parcelable object reading and writing
* read answer most voted comment - http://stackoverflow.com/questions/7042272/how-to-properly-implement-parcelable-with-an-arraylistparcelable#comment39567370_7042753
* (18/01/2017) Eido */// CONSIDER: Do we need secret key?
// (28/11/2016) Eido<!--
DOING: Add a video which constructed from h264 aac
priority on 1080p and multi speakers usage.
(06/11/2016) Eido -->/*
* TODO: Change to user friendly message
* or remove by being irrelevant for the user.
* (16/01/2017) Bob */
Hacker Noon is how hackers start their afternoons. We’re a part of the @AMI family. We are now accepting submissions and happy to discuss advertising & sponsorship opportunities.
If you enjoyed this story, we recommend reading our latest tech stories and trending tech stories. Until next time, don’t take the realities of the world for granted!
