Be Agile with Codetags

To put it simple, Agile methodology is based on quick iterations. That approach implies that: 

• We must be fast coders to complete each iteration in the scheduled time
• Soon or later we'll go back to that code we quickly wrote in the past

If we only focus in the first statement (be faster, my friend), codebase quality tends to degrade, code entropy -or the codebase maintenance complexity- increases, bugs start to consume more and more time in every sprint and, in last term, software components must be fully re-coded, what can consume great part of the benefits we got by becoming agile.

However if we have in mind that, in coming iterations, we'll have to refactor the code we are working on right now, we can document the technical debt we intentionally create with the purpose of fixing it in the future. In that way, when planning every iteration (or sprint) we can schedule a percentage of the coding effort to fix that debt we left, therefore keeping the codebase entropy under control.

In this scenario, the optimal way of documenting is doing it ad hoc, ie, in the whole source code, so the tech debt and its documentation, as source code comments, are put together. Codetagging is a not standardized convention that allows tagging pieces of source code with well-known comment labels, or mnemonics. So, for instance, if we find a comment block tagged with the mnemonic TODO, we understand that the comment is documenting a pending issue to be done in the commented source code:

function sayHello(name : string) : string {
   // TODO: Compose a different greeting if the name is an empty string
   return `Hello, ${name}!!`;
}

In the same way, we can tag a source code piece as potentially perfectible:

function getFirst(items : string[]) : string {
   // FIXME: Crashes if the array is empty
   return items[0];
}

Or we can propose improvements for future optimization stages:

function countItems() : number {
   // RFE: Don't search in parallel.
   // Searching in the second table is only necessary 
   // if no items are found in the first table
   const [tableAItems, tableBItems] = promise.all([searchInTableA(), searchInTableB()]);
   return tableAItems + tableBItems;
}

Codetag types

Below you can find a list of common codetags. It's quite extensive and maybe many of them were not of application for your purposes, but codetagging is not about all or nothing: just use those that you find of interest, or even invent new codetags that could help to improve your team results.

Mnemonic	Synonims	Meaning
TODO	MILESTONE, MLSTN, DONE, YAGNI, TBD, TOBEDONE	Informal tasks/features that are pending completion
FIXME	XXX, DEBUG, BROKEN, REFACTOR, REFACT, RFCTR, OOPS, SMELL, NEEDSWORK, INSPECT	Areas of problematic or ugly code needing refactoring or cleanup
BUG	BUGFIX	Reported defects tracked in bug database
NOBUG	NOFIX, WONTFIX, DONTFIX, NEVERFIX, UNFIXABLE, CANTFIX	Problems that are well-known but will never be addressed due to design problems or domain
REQ	REQUIREMENT, STORY	Requirements: Satisfactions of specific, formal requirements
RFE	FEETCH, NYI, FR, FTRQ, FTR	Requests For Enhancement: Roadmap items not yet implemented
IDEA		Possible RFE candidates, but less formal than RFE
???	QUESTION, QUEST, QSTN, WTF	Question: Misunderstood details
!!!	ALERT	Alert: In need of immediate attention
HACK	CLEVER, MAGIC	Temporary code to force inflexible functionality, or simply a test change, or workaround a known problem
PORT	PORTABILITY, WKRD	Workarounds specific to OS, programming language version, etc
CAVEAT	CAV, CAVT, WARNING, CAUTION	Implementation details/gotchas that stand out as non-intuitive
NOTE	HELP	Section where a code reviewer found something that needs discussion or further investigation
FAQ		Interesting areas that require external explanation
GLOSS	GLOSSARY	Definitions for project glossary
SEE	REF, REFERENCE	Pointer to other code, web link, etc
TODOC	DOCDO, DODOC, NEEDSDOC, EXPLAIN, DOCUMENT	Areas of code that still need to be documented
CRED	CREDIT, THANKS	Accreditations for external provision of enlightenment
STAT	STATUS	File-level statistical indicator of maturity of this file
RVD	REVIEWED, REVIEW	File-level indicator that review was conducted

Additional features

Apart of that defined as subject of this article, ie, avoiding technical debt, codetags have other advantadges:

• Being comments, they are applicable to virtually any programming language
• By the same reason, being comments they are innocuous for your source code
• They are easily parseable by productivity tools: You can find various codetag management tools as Visual Studio Code Extension, one of them the fantastic TODO tree
• They can be integrated with maintenance tools by automatically converting FIXME or BUG tagged comments into tickets

Summarizing

Agile methodology and code entropy have a close relationship due to the technical debt that quick cycles can impose. Instead of increasing that debt in every cycle, codetagging can help us to identify it, so it could be fixed in coming cycles.

Codetagging works well in a team shared codebase, is programming language agnostic, doesn't impose dependencies and doesn't require additional computing resources. Finally, many productivity tools allow us to manage codetags in an easy way.

Attributions

Part of the contents of this article are extracted from PEP 350 -- Codetags, by Micah Elliot.