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 you wanted to implement that ? super duper idea while coding 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 , what are they? super duper ideas 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 will solve you those problems: codetags use the term (or plural codetag , you can even codetag it! nice eh?) whenever referring to any sort of these code comments. From now and on codetag s 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 of section of code that need closer inspection or review. reminder I firstly read about this subject from which originally written by Micah Elliott in 2005. In this article, we’ll improve it a little for purposes. PEP350 — Codetags productivity How codetags are used? Codetags can be written in that supports comments. any programming language 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 ? had this weird idea? for god sake how much is it lays here? meant who Those questions can be really critical because maybe the of this “codetag” was the developer of this class when it was on and 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. author early stages, what he meant 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: /** * 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 */ TODO: Change client request from this server 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 (such as mnemonic, date, author and priority) that can be scripted by using custom variable text code snippets. Quickly writing well-formatted codetag in Android Studio IDE using Live Templates feature Mnemonics and their purpose There are numerous mnemonics mentioned in , the mnemonics I found the most useful for me are the following: PEP350 — Codetags — Mnemonics TODO - something that someone need to do someday (notnecessarily) in the below section of code. DOING - self reminder for what are you currently DOING (notnecessarily) relate to the below section of code. CONSIDER - reminder to CONSIDER some sort of things (notnecessarily) 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 (notnecessarily) 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 using snippets and your teammates precious time when they’ll read them, you’d probably want a way to 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. super duper ideas easily manage , the following recommended tools are the ones that I’m familiar with, that will provide you the solution to easily manage your codetags: As of today — “…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 ). Imdone Jesse Piascik — Organize, filter codetags and allow custom codetags syntax, available only as IntelliJ IDEA built-in tool window (including in Android Studio IDE). IntelliJ IDEA TODO You guys are welcome to that you are familiar with and I’d be happy to try and add them to the above list. share more similar tools The future Finally, after understanding the concept of codetags, how to save both your own and your teammates , and how manage them, you might already seen that we only use them as super duper ideas reminders. Currently, I don’t know if there are tools to generate the output of the purposes I’ll mention below, but you also use them for the following purposes: might 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 with its ). Imdone GitHub integration Use your imagination while using codetags and you’ll find them useful for more than just . maybe reminders Examples /** * Also handle the login result* (29/01/2017) Demeter */ TODO: Implement Json send via socket /** * read answer most voted comment - http://stackoverflow.com/questions/7042272/how-to-properly-implement-parcelable-with-an-arraylistparcelable#comment39567370_7042753* (18/01/2017) Eido */ FIXME: parcelable object reading and writing // // (28/11/2016) Eido CONSIDER: Do we need secret key? <!-- priority on 1080p and multi speakers usage.(06/11/2016) Eido --> DOING: Add a video which constructed from h264 aac /** * or remove by being irrelevant for the user.* (16/01/2017) Bob */ TODO: Change to user friendly message
