13 ms·

Keeping track of technical debt in source code

168 points by philou 10y ago

Safety1stClyde 10y ago
The simpler you can make these things, the more robust they will be.
tyingq 10y ago
Curious why you would track tech debt separately from other things that drive code changes...new work, defects, etc. Is this because it allows the devs more control over priority...like putting it in the work queue might result in outsiders deciding priority?
- rdiddly 10y ago
  Can't speak for the author, but to me "technical debt" is needed fixes that don't quite fit in a bug report because they don't fix any bug, and they don't deserve a feature request because they don't add features. Therefore your taskmaster/overlord/scrum-master has no place to put them and in fact you'll have trouble convincing anyone, especially non-coders, that it needs to be done at all. So, track it in the code, since devs are the target audience and since "in the code" is where you'll be the next time you find yourself having to deal with "that kludge" again.
  - Terr_ 10y ago
    There are also some organizations where the ticket backlog management... Well, old bug reports are sometimes deleted because "anything before this date probably is obsolete." That's why sometimes the code is a better spot to leave a hint for the next poor sap -- or yourself -- who stumbles across the thing again.
- wruza 10y ago
  You don't want to create 15 detailed issues each time you refactor 5-15 hour old project or feature branch. Merging these into trunk/master is obviously less meaningful. // FIXME bad wording? Todos (and fixme, xxx) are very useful as review or editing anchors.
  - tyingq 10y ago
    That makes sense...It was the tie to "tech debt" that made it sound long lived.
    - wruza 10y ago
      It really depends. My usual routine for brand new projects is to init RCS/tracking only once something meaningful emerges, and that time may vary. For "research" projects I simply don't do that, because initial refactoring history has no value and project is copy-and-throwaway anyway. Marker comments may be the only tracking method there. Once code is moved into real workdir, all todos are subject to regular issue tracking.
  - Silhouette 10y ago
    I agree. For me, TODO-style comments are very useful for stuff I'm currently working on, as a short term aid. Usually I wouldn't be committing them, except for things like short-lived commits on a working branch that will be rebased out later. For example, if I'm adding a substantial new feature and it will affect the code in a few different places, I'll often go through first and leave easily searchable markers at the exact locations where I expect to make changes. Then I can do a quick comparison between where I'd expect to need changes given the design and where I've found to make them to ensure they match up before I start changing anything, and then I can move quickly through all of the required changes without losing focus.
- webignition 10y ago
  At an organisation I recently worked for we did both. Technical debt tickets were created in the issue tracker. The ticket offers plenty of space to detail the technical reasons for implementing potentially suboptimal code in the first place (a justification for the introduction of technical debt), a general outline of the approach to resolving the debt and to list out business justifications for resolving the debt. A TODO comment referencing the ticket was added to the code. This reduced comment bloat and allowed a developer to easily find the relevant source from a ticket and vice versa. Technical debt issues were added to each sprint/development cycle by product managers with developer input during planning sessions. This process also had the benefit of letting developers fill in small amounts of possible development downtime. If you know you have to leave the office in 30 mins (a dentist appointment for example that you can't miss), you may be uninclined to start work on a large feature. Picking up almost any small tech debt ticket turns that time into something more productive than nothing.
- jacques_chester 10y ago
  Where I work, they fall under the heading of "chores", for which the usual definition given is "something that will improve future velocity". Engineering owns these and gets to prioritise them as necessary. It's usually done with an eye to the current backlog of stories and bugs that product has prioritised. Sometimes chores get done opportunistically. You have a time gap, you grab a short chore and do it. Or you might spin one out of a story as a kind of marker of known tech debt. Sometimes engineering sees a heavy piece of tech debt that is a millstone and just goes ahead with it. Usually this ties up a track of work that becomes unavailable for product work, sometimes for weeks.
- jes5199 10y ago
  in my experience, non-coders read the other work queues, and might try to interfere with the list, even though it's completely outside their domain
partycoder 10y ago
Technical debt becomes harder to refactor as more code depends on it. Then, there needs to be awareness and a sense of urgency. Technical debt accrues interest. In my case, I use deprecation tags: - @deprecated on javadoc for Java (http://download.java.net/java/jdk9/docs/api/java/lang/Deprecated.html http://download.java.net/java/jdk9/docs/api/java/lang/Deprec...), JSDoc for JavaScript (http://usejsdoc.org/tags-deprecated.html http://usejsdoc.org/tags-deprecated.html), Yard for Ruby (http://www.rubydoc.info/gems/yard/file/docs/Tags.md#deprecated http://www.rubydoc.info/gems/yard/file/docs/Tags.md#deprecat...) - Obsolete attribute on .NET (https://msdn.microsoft.com/en-us/library/22kk2b44(v=vs.90).aspx https://msdn.microsoft.com/en-us/library/22kk2b44(v=vs.90).a...) - deprecated pragmas and macros in C++ - DeprecationWarning on Python (https://docs.python.org/3/library/warnings.html#warnings.warn https://docs.python.org/3/library/warnings.html#warnings.war...) By doing this: - You get a deprecation warning. - Some editors may highlight it. This signals people to stop using that code. This creates a sense of urgency to switch to or create a refactored alternative that is cleaner.
- marcomonteiro 10y ago
  +1 Though I do leave the occasional TODO or FIXME comment in code I prefer using deprecation attributes so that it results in a compiler warning. I spend a lot of time in Xcode so for me I like that autocomplete shows the method with a strikethru and the compiler warning is highlighted inline. It becomes glaringly obvious to everyone that we're adding to the technical debt by using the API.
- doctorpangloss 10y ago
  > Then, there needs to be awareness and a sense of urgency. Technical debt accrues interest. An alternative interpretation is that technical debt depreciates. That is, in a Darwinian way, clearly the product survived WITHOUT implementing the changes someone thought it needed. So is it really technical debt, or just baggage? Sometimes, debts are written down.
  - webmaven 10y ago
    Sure, and sometimes you have to declare tech bankruptcy, and just do a rewrite from scratch (often accompanied by a switch in framework or programming language). Whether it is "baggage" or "debt" depends on whether it is accumulating interest (that is, it makes other changes such as adding features harder and harder to do).
mfukar 10y ago
In no codebase or organisation I've ever worked in were comments actionable information. Some technical debt spans multiple lines, or across files, modules, etc. Issue trackers are everywhere nowadays. You've found something that needs doing? File an issue. Treat it like any other, it's not special.
- maccam94 10y ago
  There's different sizes of TODO. For anything beyond small cleanups, yeah, an issue is probably warranted. But, filing tasks in the issue tracker aren't always the best solution either. They often become out of sync with the state of the code, and who's going to trawl through all of those low-priority issues on a regular basis? To mitigate the de-synchronization, I tend to embed links to the issue in the comment like: # TODO: Frob the foobar issue #4376
  - mfukar 10y ago
    The only way an issue about technical debt becomes irrelevant is the debt is not there any more. I don't know how others treat an issue tracker; on my team, we go through issues at the start of every sprint and possibly re-prioritise. Issue became irrelevant? Close. Move on.
  - dllthomas 10y ago
    > They often become out of sync with the state of the code I try to write a test when I open a ticket, demonstrating the desired behavior, and mark it such that it's checked for failure (so we notice if we've fixed it in passing) unless an environment variable is set to the particular ticket number. Sometimes I also include a test demonstrating current behavior - this helps surface the tickets if someone is working on something related.
- bunderbunder 10y ago
  Issue trackers are good for long treatment and allowing people to prioritize and schedule fixes for technical debt. They're also somewhere that issues might go to die - in many orgs, it's common to basically ignore anything in the backlog that isn't being actively championed by a team member or customer. The nice thing about putting todos in the code is, somebody will see that the next time they're working on that chunk of code. The bad thing is that they're highly localized, and frequently give little space to give a full explanation of the problem. The combination solution that really does get you the best of both worlds is to create a ticket, and then reference the ticket # with TODOs when there are bits of the code that are influenced by that technical debt. That way if you're seeing a todo in the code, you can easily get to a central ticket with more information. But also, when you're working on one of those tech debt tickets, you can search for the ticket # in the code base to verify that you really have found all known (by which I mean, somebody cared enough to make a note of it) places where the tech debt is manifesting itself in the code. Also, tech debt is less likely to become a dead letter. Programmers read the code incidentally to their work. The only people who habitually read the ticket queue incidentally to their work have PMO certifications.
dugmartin 10y ago
I added this VS code extension recently that highlights TODOs: https://marketplace.visualstudio.com/items?itemName=wayou.vscode-todo-highlight https://marketplace.visualstudio.com/items?itemName=wayou.vs... Works well for me as I'm working through new code or refactoring since it makes the TODOs stick out so much against the dark theme I use.
- Tempest1981 10y ago
  VisualAssist has a hashtag feature that also works nicely: https://docs.wholetomato.com/default.asp?W574 https://docs.wholetomato.com/default.asp?W574 Eg: // #TODO refactor
- j_s 10y ago
  Visual Studio's Task List window's Comments view will show comments with the following (configurable) keywords: • HACK • TODO • UNDONE • UnresolvedMergeConflict
dorianm 10y ago
Maybe every comment is a TODO, as some better, clearer, simpler code wouldn't need comments?
- andrewfong 10y ago
  http://ericholscher.com/blog/2017/jan/27/code-is-self-documenting/ http://ericholscher.com/blog/2017/jan/27/code-is-self-docume...
  - tchaffee 10y ago
    Lately I've been finding a thorough test suite to be better at documenting code than comments. But I have to chuckle at "self documenting" every time I hear it.
sambe 10y ago
This pre-supposes a team of people who care about technical debt. I remember Eclipse in the early 2000s was already doing this (FIXME, TODO and something else IIRC). In my experience there are lot of productive programmers who, overall, add value (stuff gets done, it's not a bug-infested disaster) but simply don't care. Might not even have heard the expression technical debt. Might care more about short-term reputation wins from Getting Stuff Done. They aren't going to leave TODOs.
- johnfn 10y ago
  If the programmers are productive in the code, as you admit, then why would they need to spend time clearing TODOs?
  - sambe 10y ago
    Short-term productive.
jsdalton 10y ago
Interesting that the author highlights CodeClimate's "support" of TODO comments via the FixMe engine. The problem is that the TODOs get flagged as failures in the context of a pull request and require a manual override. The overall attitude in the tooling is TODOs as a code smell or problem vs. a solution. Maybe this is not a big deal (since you can interpret the information however you choose) but it creates cultural resistance to embracing TODOs. We've recently started dabbling with TODOs again on my team but I still haven't overcome a bit of guilt I feel, like maybe "I'm doing it wrong" -- even though I think TODOs are a perfect fit for highlighting small tidbits of technical debt as the author describes here.
- brynary 10y ago
  (Founder of Code Climate here.) This is really good feedback, which we are addressing. We're going to change things up so that by default TODO issues are emitted as "Info" severity instead of "Minor", and we are going to change our PR integration so it does not fail PRs on "Info" issues. As an aside, on Tuesday we launched a Grep engine, which is much more powerful than FIXME: https://codeclimate.com/changelog/58ecfa297705a149790008b2 https://codeclimate.com/changelog/58ecfa297705a149790008b2 It allows full customization of the emitted issues.
reledi 10y ago
My advice is to never place TODO comments in your code. It will become a graveyard for TODOs and annoy fellow programmers who come across it for years after it was written. Instead 1. Quickly experiment with refactoring but stop if it feels wrong. We often underestimate how quickly we can improve the codebase. It's often better to try something quickly than waste time planning to do it. 2. Defer if it's a big refactor or you're on a very tight deadline. Write a reminder in your physical notebook so you don't prematurely pollute your board. If it feels high priority after that and you still haven't had time to do it, then make a chore ticket for it.
- Normal_gaussian 10y ago
  I completely disagree Placing TODO and ASAPs in code helps ensure you don't leave any loose ends, and if you call another developer onto your feature branch allows them to get a feel for how you're getting on and how complete the code is. Using a physical notebook distances the workload from the code and hides the fact something is incomplete from others. A TODO graveyard can be prevented when you review the code - a developer who thinks a feature branch littered with TODO annotations is complete code is either dreaming up future use cases or failing to complete the work assigned.
  - pepve 10y ago
    I think you're both right. It's okay to have them locally or on feature branches for communication and note taking purposes. But they should never live for any prolonged time in your production code.
  - TeMPOraL 10y ago
    I'm with you here. > Using a physical notebook distances the workload from the code and hides the fact something is incomplete from others. Exactly. In fact, I use both (except the notebook is an org-mode file, not a dead-tree book). TODOs / FIXMEs in code are for things very context-dependent and connected to code, for which it's important to see them in surrounding context. In more abstract cases, I just log a task in my notebook, to be done later. Examples of both - code: //TODO resourcify (i.e. move to external string resources database later) vs. notebook: ** TODO Refactor the refactor of the SomeClass class. -- Also, often TODO / FIXME comments serve for me as anchors in some larger refactoring processes. I tend to label them specifically for easy grepping (e.g. with unique Unicode chars like ). The point is, refactoring process may take few days, during which I also may need to do some other tasks, so whenever there's a piece of code that needs to be redone but not right now, I tag it for later; I can then use grep/IDE search to check if I didn't miss anything.
stuaxo 10y ago
I've been doing this for a while, you need to be sparing with it though.
TeMPOraL 10y ago
My way is simple - I occasionally grep the whole codebase for "TODO", "FIXME" and "HACK", and review the results, trying to either immediately fix them or turn into actionable items. At my $dayjob I do Java, for which the IDE also lets me conveniently view the TODO/FIXME entries. I also have Sonar, which reminds me of them through low-importance warnings.
- jbernardo95 10y ago
  This tools helps you with that process https://github.com/ahmadassaf/code-notes https://github.com/ahmadassaf/code-notes
  - TeMPOraL 10y ago
    Thanks for the link, it looks nice. I'll consider it if I ever start doing anything in Node. At the moment, however, I prefer it simple: In Fish Shell I have: function grp grep -rni $argv end and I simply do "grp todo", "grp fixme", etc. Example output (it's actually also colored): src/main.lisp:63: ;; TODO FIXME introduce at some point a mapping for page list -> generation function, or something. src/main.lisp:89:;;; FIXME deprecated src/main.lisp:94:;;; FIXME unused and probably throwaway src/site-components.lisp:9: ;; FIXME use some page structure map to map from (name language) to base filepath src/site-components.lisp:31: (let ((colorize:*css-background-class* "no-paren-fx")) ;FIXME make configurable maybe? That's good enough for me :). Also I have appropriate highlights set up in editors & IDEs I use :).
    - PerfectDlite 10y ago
      IDEA has separate TODO tab, which can also display TODO regarding your scope - e.g. your current changes.
- nobodyorother 10y ago
  IIRC, most Java IDEs also natively support XXX as an alternative to HACK. "sed 's/HACK/XXX/g'" to the rescue?
luke-stanley 10y ago
To find the todos I can do: git grep -EI "TODO|FIXME" Then if I want numbers I can do: git grep -EI "TODO|FIXME" |wc --line Credit to https://www.commandlinefu.com/commands/view/12842/get-a-list-of-all-todofixme-tasks-left-to-be-done-in-your-git-project https://www.commandlinefu.com/commands/view/12842/get-a-list...
- ziikutv 10y ago
  Same, but I use AG.
  - softawre 10y ago
    Same, but I use rg.
    - rok3 10y ago
      Same but I use: cat | Mk1 eyeball In all seriousness, the great thing about a standard like this is that it is tool agnostic.
jwineman 10y ago
A good way to minimize technical debt is to block PRs that have TODOs until the author completes them, therefore eliminating the technical debt they would have otherwise introduced.
- crusso 10y ago
  Although I wonder how much self-censorship that encourages. Whether or not to put a TODO in your code is a judgement call. If you tell some developers that admitting to a TODO means that they can't submit, they might not admit to them as often. It's a bit case-by-case, but I think I'd rather encourage contributors to admit to the lacks in their code and accept them - but get them to commit to follow ups that will fix the problems.
- DenisM 10y ago
  You're killing the messenger.
- abraham 10y ago
  This is likely to lead to developers just leaving out the TODOs instead of doing the work. Especially for work that isn't needed now but should be done at some point in the future.
- bobbytherobot 10y ago
  You aren't blocking technical debt, you are simply blocking TODO comments.
- aero142 10y ago
  How's that job you work at without deadlines and where engineering is the most important department?
- softawre 10y ago
  You should go be a team lead, get some deadlines - and the perspective that comes with it.
tchaffee 10y ago
I thought this technique was such common knowledge that I kept waiting for the punchline in the article. It was a good reminder that even the simple stuff deserves to be written about and revisited every so often.
- cjhanks 10y ago
  They were even written as a PEP nearly 12 years ago. https://www.python.org/dev/peps/pep-0350/ https://www.python.org/dev/peps/pep-0350/
  - metaobject 10y ago
    It appears that the status of that PEP is "rejected".
- temp246810 10y ago
  The author mentions this themselves: >>>The great thing about TODO comments is that, as a very old programming trick, they are already supported out of the box by most tools IntelliJ, SonarQube, Rails, CodeClimate and I guess many others. Only one day after I refactored to TODO comments, a team mate fixed one that had appeared in his IDE’s TODO tab
NicoJuicy 10y ago
I thought this was only in Visual Studio, guess i'm wrong. PS. In VS - Go to View: "Task List", it gives an overview of all TODO's.
- matwood 10y ago
  Intellij also has this functionality. I use it as a task list when working on features that span different sections of a project.
peterwwillis 10y ago
A lot of hate for TODO/FIXME in the comments... We've been using them successfully in open source for decades. I would never rely on them between releases, but during active development of a single release they are handy. A single line is not enough to explain work needed to be done or getting said work done, but it can be enough to explain existing work, sometimes.
gtrubetskoy 10y ago
I like the way the Golang team handled the introduction of Contexts. Adding them required a lot of re-thinking, and so they added a Context.TODO() method which returned a context stub essentially. Something similar could be used with todo comments in general, e.g. in your favorite language something along the lines of: import todo todo.add("Fix this later") Which would keep track of those and you can somehow automate reporting, various restrictions and what not. [1] https://golang.org/pkg/context/#TODO https://golang.org/pkg/context/#TODO
Cerium 10y ago
I've been taught to keep these out of production code. If your code fails in a way that gets you in a lawsuit you won't want to be explaining what that "TODO: looks like a xxx here" means to the judge.
- crusso 10y ago
  Maybe if you're coding the algorithm for when to deploy airbags or something similarly life-protecting - but many of us are just coding todo list web sites and the next social media app. As much of a rule-follower as I am... I think that if I always had to code for the eventual lawsuit, I'd quit coding.
- Ensorceled 10y ago
  I guess you don't file bug reports either?
  - Cerium 10y ago
    We file bug reports and fix the bugs, but we are not allowed to ship a faulty product to our customers.
    - TheCoelacanth 10y ago
      Then you must either have NASA level QA or never ship a product. Most software companies can't afford either of those.
bobbytherobot 10y ago
You can pair the TODO with the issue tracker. // TODO(<Issue Number>): <Short message>
mnarayan01 10y ago
More in reference to the comments here than the actual article, but TODOs in the comments can be used to transmit what I find to be useful information: $THING was on the writer's radar, but $THING is not handled (correctly or not) in some non-obvious manner. If your project uses them to indicate e.g. things that can not be merged into master, then obviously that's one thing, but when they're simply comments, the hate here seems misplaced. Other than (maybe) redis, I don't think I've ever seen code that did not have "potential things to do" that would have been nice to see commented.
lloydde 10y ago
In a couple of work environments, people would initial the TODO -- I'm trying to remember if Joyent is one of those companies. I liked this, because it was extra honesty about the craft and I could pick the person's brain if there were issues in that code. It would also seem to allow to get a TODO brain dump when someone is planning on leaving the company or assist in who to bring to the table for refactoring of a large component.
- veneratio 10y ago
  Tagging TODOs is really useful. I can always look at source control, but that's more effort than seeing a name or bug number. At Google our linters are actually configured to create errors for any TODO/FIXME that isn't immediately followed by a user id or bug number: e.g. TODO(12345) or TODO(myname). I thought it was a little annoying at first, but over time I've realized how much faster it is to have that additional context.
  - dmi 10y ago
    I think it's important to highlight that it's definitely about context rather than ownership when adding a name or bug number to a TODO comment. "// TODO(dmi): update after moving to Java8" doesn't necessarily mean that it's _me_ that has to fix it, but that someone can come to me and say "Tell me more about this". This took me a while to learn/remember, but it's very helpful. The hardest part for me to keep in mind was that someone else's name on a TODO shouldn't mean I ignore it.
- jwhitlark 10y ago
  I've found that a time stamp is super useful in TODOs, etc.
  - WorldMaker 10y ago
    Timestamps and Users that added TODOs should be available from the praise/annotate/blame tools of your source control system.
gregshap 10y ago
I see TODO's in production code as only somewhat better than commenting out 'almost working' code. It helps me understand the original intent of the developer, but I don't trust that it's actually the right thing to do, and mostly shouldn't be there.
iopuy 10y ago
The best solution I have found is to use TODO (so it is grep-able) but then add a colon followed by your initials. E.G. //TODO: JTF, Use new error handling strategy here This way it is clear who put it there and makes it MUCH easier to keep track of your debt and not your buddies.
- OJFord 10y ago
  Or just `git blame` the line?
  - iopuy 10y ago
    No, this will take into account any changes in spacing which are legit changes that sometimes need to be made but have no effect on the logic of the commented routine.
snird 10y ago
In my opinion, this is a bad practice. 1. It prevents discussion. Whomever wrote the "TODO" solemnly decides what is there "TODO", without the ability to discuss options. 2. It does not allow prioritization of tasks easily. 3. You need yet another tool to discover issues. 4. It prevents ownership of an issue. All those issues have already been solved with a simple ticket system (github issues, JIRA tickets etc'). Why reinvent the wheel? What is the benefit here?
- pavel_lishin 10y ago
  > All those issues have already been solved with a simple ticket system (github issues, JIRA tickets etc'). Why reinvent the wheel? What is the benefit here? The #TODO comments live close to the code. If it gets updated (whether that's an actual fix for the tech debt while working in the area, or removing code altogether due to refactoring, there's no guarantee that the ticket will get updated - and then you spend time trying to figure out which actual tech debt tickets are up to date or not. It also means that they're easily discoverable - you can stumble on one while working on something, without having to hunt through Jira for what to fix. You're also likely to understand how to fix it without having to come up to speed, since you're already working in that code.
- kbenson 10y ago
  You are describing policy issues with a technical solution. The solution to policy issues such as those is to make it policy to only use the solution at appropriate times. If you only allows TODO after a discussion (e.g. TODO: We decided to forego implementing X at this time, but we may need it later, as per project lead Y). It does not prevent prioritization or ownership, and there's nothing to prevent a corresponding entry in some management system (and indeed, you can put the ID from that system in the TODO). That said, often there's things you want to signpost specifically for future developers (including yourself) which may not rise to the level of needing a ticket assigned or external tracking (or that may be complicated due to bureaucracy or or you measure goals being met). There are plenty of reasons to have an additional channel to signal information directly to a dev. Just don't make that instead off the official channels of communication without good cause.
skybrian 10y ago
TODO's are for things that are optional to fix and probably won't be fixed. Sometimes not fixing something is the right move, but you leave a signpost that you deliberately skipped it. Someone else, later, can pick it up, if they choose. Whether fixed or not, it's valuable to future readers to know there's a gap.
- degenerate 10y ago
  This is exactly what I use them for and it works well. They are like the "falling rocks" signs on roads. The "TODO" is to make the entire cliffside completely safe, but as long as everyone is watching for rocks when driving (coding) in this section, that suffices.
- pc2g4d 10y ago
  I tend to use TODO for features/functionality I'd like to add, and FIXME for existing functionality that's not doing what we want. Obviously there's a fuzzy line there.
- robmaister 10y ago
  I will usually also include //HACK comments with a little note as to what is broken or what my assumptions were at the time of writing, for things that I believe are likely to cause breakage later on. TODOs are for optional/longer-term things as you described, like inefficient implementations because the current assumption is that it will ever only operate on 20 elements. HACKs are more along the lines of "hey if you're debugging this bit of code, your issue is probably here"
heisenbit 10y ago
This may be a technique to support tracking of technical debt IN your source code IFF it can be attributed to a specific place. Some of the more vexing debt is across the code, in the systems around the system being build or in the tool chain and needs other types of tracking.
tonto 10y ago
One way I thought of doing this would be to just have every commit tagged with some subjective score given by the committer (in commit message), probably just 1,2,3 to avoid too much weird subjectivity of a x/10 ranking, that gives how much the user subjectively thinks a commit is janky. then you will get a map of source code quality over time
plandis 10y ago
On my team at work we require all todos to link to a tracking issue (think like JIRA, etc...) That way it's 1.) Clear what the context on the todo is 2.) It's clearly in our backlog and can be prioritized accordingly. We have some scripts that run at build time to verify all todos have the appropriate issue as well as manual code reviews on all changes and I honestly don't remember the last time it was done incorrectly.
awaisraad 10y ago
There's also // FIXME
paulddraper 10y ago
1. If you are going to write TODO, write TODO(paul) or similar, so that you easily know the originator. 2. Unless the dev team is very small, most TODOs belong in your issue tracking system. That's where they can be enumerated, described, discussed, prioritized, assigned, etc.
gumby 10y ago
I was weirded out by this line: "Some tools, IDEs in particular, tend to assume that you should fix all your TODOs before you commit anything." Holy crap that's fragile! I'm still looking for the value add of an IDE. I'm not negative toward them (I know many many people use them and get a lot of value out of them) but I personally have never found one that was easier than simply writing and compiling code. Could be my use cases (the kind of code I write/projects I do).
- l0b0 10y ago
  Ditto until relatively recently. Vim, Emacs, jEdit, Notepad++ until about four years ago when I tried IntelliJ IDEA. Never looked back. It was also an eye opener about the limits of tool support in loosely typed languages.
  - gumby 10y ago
    I have a colleague using IDEA for the part of our project that's in Java. There's a continuous stream of curses coming from his desk and he's been programming in Java since it was first announced by Sun. Part of the problem I think is taking your hands of the keyboard to manipulate the mouse.
antirez 10y ago
The first comment in the blog post is great about using XXX, TODO and FIXME for different types of debt.
retreatguru 10y ago
I have been doing this for years. I find it helpful when going to refactor a part of the app that has problems. I then go look in the code and see TODO comments I added a while ago. Then I am 100% sure I really should fix that up. Yes they can get stale but usually they tend to be helpful. I really like reading todos written by other devs to see where a feature was left incomplete. It's so much easier to see it right in the code rather than lost in a ticketing system.
x21 10y ago
I recently finished writing my master's thesis on "the impact of self-admitted technical debt on software quality" [2], we use the same approach this article advocates to identify this type of technical debt, which we call "self-admitted technical debt" (SATD) [1]. We examined the impact of SATD on software quality for forty open-source projects. To measure this, we took into account three criteria commonly associated with quality: (i) on the file level, the relationship between defects and SATD; (ii) on the change level, the potential of SATD to introduce future defects and (iii) the complexity SATD changes impose on the system. The results of our study indicate that: (i) SATD and defects exhibit no correlation at the file level, (ii) SATD changes make the system more susceptible to future defects than non-SATD changes do and (iii) SATD changes are more difficult to perform on the system. [2] (an abbreviated version [3]) There are more patterns to identify technical debt than "TODO, FIXME or XXX". You can find the rest of the patterns here [1]. It is very interesting to see developers confessing their workarounds and hacks through source code comments, as it can alert later contributors to the technical debt induced. References: [1] http://das.encs.concordia.ca/uploads/2016/01/Potdar_ICSME2014.pdf http://das.encs.concordia.ca/uploads/2016/01/Potdar_ICSME201... [2] https://www.scribd.com/document/345197805/Sultan-Wehaibi-master-s-thesis?secret_password=Zq5b32lVkHiyitBuQ1nQ https://www.scribd.com/document/345197805/Sultan-Wehaibi-mas... [3] http://das.encs.concordia.ca/uploads/2016/01/Wehaibi_SANER2016.pdf http://das.encs.concordia.ca/uploads/2016/01/Wehaibi_SANER20...
webninja 10y ago
Meanwhile, at the Indian contracting company where I currently work, I came across a few lines of code in a phone application that no longer logged data to a log file. I was told that it had been there for a number of years. As I went to instinctually remove it, I was told by my supervisor that "we don't remove anything unless we get a Code Cleanup task". Cleaning up the code now would be "Out of Scope". It's no wonder now how this project has 1M lines of code and 10K files... Garbage in, nothing out.
- Too 10y ago
  Engineers who only do exactly what management tells them to do should be thrown out with the head first. If management knew exactly what has to be done there wouldn't be a need for engineers in the first place.
ascotan 10y ago
The google style guide for c++ actually has a recommended format for TODO's where the author is in parens: // TODO(author): fix this that way you know who was TODO'ing

168 points by philou 10y ago

The simpler you can make these things, the more robust they will be.

Curious why you would track tech debt separately from other things that drive code changes...new work, defects, etc. Is this because it allows the devs more control over priority...like putting it in the work queue might result in outsiders deciding priority?

rdiddly 10y ago
Can't speak for the author, but to me "technical debt" is needed fixes that don't quite fit in a bug report because they don't fix any bug, and they don't deserve a feature request because they don't add features. Therefore your taskmaster/overlord/scrum-master has no place to put them and in fact you'll have trouble convincing anyone, especially non-coders, that it needs to be done at all. So, track it in the code, since devs are the target audience and since "in the code" is where you'll be the next time you find yourself having to deal with "that kludge" again.
- Terr_ 10y ago
  There are also some organizations where the ticket backlog management... Well, old bug reports are sometimes deleted because "anything before this date probably is obsolete." That's why sometimes the code is a better spot to leave a hint for the next poor sap -- or yourself -- who stumbles across the thing again.
wruza 10y ago
You don't want to create 15 detailed issues each time you refactor 5-15 hour old project or feature branch. Merging these into trunk/master is obviously less meaningful. // FIXME bad wording? Todos (and fixme, xxx) are very useful as review or editing anchors.
- tyingq 10y ago
  That makes sense...It was the tie to "tech debt" that made it sound long lived.
  - wruza 10y ago
    It really depends. My usual routine for brand new projects is to init RCS/tracking only once something meaningful emerges, and that time may vary. For "research" projects I simply don't do that, because initial refactoring history has no value and project is copy-and-throwaway anyway. Marker comments may be the only tracking method there. Once code is moved into real workdir, all todos are subject to regular issue tracking.
- Silhouette 10y ago
  I agree. For me, TODO-style comments are very useful for stuff I'm currently working on, as a short term aid. Usually I wouldn't be committing them, except for things like short-lived commits on a working branch that will be rebased out later. For example, if I'm adding a substantial new feature and it will affect the code in a few different places, I'll often go through first and leave easily searchable markers at the exact locations where I expect to make changes. Then I can do a quick comparison between where I'd expect to need changes given the design and where I've found to make them to ensure they match up before I start changing anything, and then I can move quickly through all of the required changes without losing focus.
webignition 10y ago
At an organisation I recently worked for we did both. Technical debt tickets were created in the issue tracker. The ticket offers plenty of space to detail the technical reasons for implementing potentially suboptimal code in the first place (a justification for the introduction of technical debt), a general outline of the approach to resolving the debt and to list out business justifications for resolving the debt. A TODO comment referencing the ticket was added to the code. This reduced comment bloat and allowed a developer to easily find the relevant source from a ticket and vice versa. Technical debt issues were added to each sprint/development cycle by product managers with developer input during planning sessions. This process also had the benefit of letting developers fill in small amounts of possible development downtime. If you know you have to leave the office in 30 mins (a dentist appointment for example that you can't miss), you may be uninclined to start work on a large feature. Picking up almost any small tech debt ticket turns that time into something more productive than nothing.
jacques_chester 10y ago
Where I work, they fall under the heading of "chores", for which the usual definition given is "something that will improve future velocity". Engineering owns these and gets to prioritise them as necessary. It's usually done with an eye to the current backlog of stories and bugs that product has prioritised. Sometimes chores get done opportunistically. You have a time gap, you grab a short chore and do it. Or you might spin one out of a story as a kind of marker of known tech debt. Sometimes engineering sees a heavy piece of tech debt that is a millstone and just goes ahead with it. Usually this ties up a track of work that becomes unavailable for product work, sometimes for weeks.
jes5199 10y ago
in my experience, non-coders read the other work queues, and might try to interfere with the list, even though it's completely outside their domain

partycoder 10y ago

Technical debt becomes harder to refactor as more code depends on it. Then, there needs to be awareness and a sense of urgency. Technical debt accrues interest. In my case, I use deprecation tags: - @deprecated on javadoc for Java (http://download.java.net/java/jdk9/docs/api/java/lang/Deprecated.html http://download.java.net/java/jdk9/docs/api/java/lang/Deprec...), JSDoc for JavaScript (http://usejsdoc.org/tags-deprecated.html http://usejsdoc.org/tags-deprecated.html), Yard for Ruby (http://www.rubydoc.info/gems/yard/file/docs/Tags.md#deprecated http://www.rubydoc.info/gems/yard/file/docs/Tags.md#deprecat...) - Obsolete attribute on .NET (https://msdn.microsoft.com/en-us/library/22kk2b44(v=vs.90).aspx https://msdn.microsoft.com/en-us/library/22kk2b44(v=vs.90).a...) - deprecated pragmas and macros in C++ - DeprecationWarning on Python (https://docs.python.org/3/library/warnings.html#warnings.warn https://docs.python.org/3/library/warnings.html#warnings.war...) By doing this: - You get a deprecation warning. - Some editors may highlight it. This signals people to stop using that code. This creates a sense of urgency to switch to or create a refactored alternative that is cleaner.

marcomonteiro 10y ago
+1 Though I do leave the occasional TODO or FIXME comment in code I prefer using deprecation attributes so that it results in a compiler warning. I spend a lot of time in Xcode so for me I like that autocomplete shows the method with a strikethru and the compiler warning is highlighted inline. It becomes glaringly obvious to everyone that we're adding to the technical debt by using the API.
doctorpangloss 10y ago
> Then, there needs to be awareness and a sense of urgency. Technical debt accrues interest. An alternative interpretation is that technical debt depreciates. That is, in a Darwinian way, clearly the product survived WITHOUT implementing the changes someone thought it needed. So is it really technical debt, or just baggage? Sometimes, debts are written down.
- webmaven 10y ago
  Sure, and sometimes you have to declare tech bankruptcy, and just do a rewrite from scratch (often accompanied by a switch in framework or programming language). Whether it is "baggage" or "debt" depends on whether it is accumulating interest (that is, it makes other changes such as adding features harder and harder to do).

mfukar 10y ago

In no codebase or organisation I've ever worked in were comments actionable information. Some technical debt spans multiple lines, or across files, modules, etc. Issue trackers are everywhere nowadays. You've found something that needs doing? File an issue. Treat it like any other, it's not special.

maccam94 10y ago
There's different sizes of TODO. For anything beyond small cleanups, yeah, an issue is probably warranted. But, filing tasks in the issue tracker aren't always the best solution either. They often become out of sync with the state of the code, and who's going to trawl through all of those low-priority issues on a regular basis? To mitigate the de-synchronization, I tend to embed links to the issue in the comment like: # TODO: Frob the foobar issue #4376
- mfukar 10y ago
  The only way an issue about technical debt becomes irrelevant is the debt is not there any more. I don't know how others treat an issue tracker; on my team, we go through issues at the start of every sprint and possibly re-prioritise. Issue became irrelevant? Close. Move on.
- dllthomas 10y ago
  > They often become out of sync with the state of the code I try to write a test when I open a ticket, demonstrating the desired behavior, and mark it such that it's checked for failure (so we notice if we've fixed it in passing) unless an environment variable is set to the particular ticket number. Sometimes I also include a test demonstrating current behavior - this helps surface the tickets if someone is working on something related.
bunderbunder 10y ago
Issue trackers are good for long treatment and allowing people to prioritize and schedule fixes for technical debt. They're also somewhere that issues might go to die - in many orgs, it's common to basically ignore anything in the backlog that isn't being actively championed by a team member or customer. The nice thing about putting todos in the code is, somebody will see that the next time they're working on that chunk of code. The bad thing is that they're highly localized, and frequently give little space to give a full explanation of the problem. The combination solution that really does get you the best of both worlds is to create a ticket, and then reference the ticket # with TODOs when there are bits of the code that are influenced by that technical debt. That way if you're seeing a todo in the code, you can easily get to a central ticket with more information. But also, when you're working on one of those tech debt tickets, you can search for the ticket # in the code base to verify that you really have found all known (by which I mean, somebody cared enough to make a note of it) places where the tech debt is manifesting itself in the code. Also, tech debt is less likely to become a dead letter. Programmers read the code incidentally to their work. The only people who habitually read the ticket queue incidentally to their work have PMO certifications.

dugmartin 10y ago

I added this VS code extension recently that highlights TODOs: https://marketplace.visualstudio.com/items?itemName=wayou.vscode-todo-highlight https://marketplace.visualstudio.com/items?itemName=wayou.vs... Works well for me as I'm working through new code or refactoring since it makes the TODOs stick out so much against the dark theme I use.

Tempest1981 10y ago
VisualAssist has a hashtag feature that also works nicely: https://docs.wholetomato.com/default.asp?W574 https://docs.wholetomato.com/default.asp?W574 Eg: // #TODO refactor
j_s 10y ago
Visual Studio's Task List window's Comments view will show comments with the following (configurable) keywords: • HACK • TODO • UNDONE • UnresolvedMergeConflict

dorianm 10y ago

Maybe every comment is a TODO, as some better, clearer, simpler code wouldn't need comments?

andrewfong 10y ago
http://ericholscher.com/blog/2017/jan/27/code-is-self-documenting/ http://ericholscher.com/blog/2017/jan/27/code-is-self-docume...
- tchaffee 10y ago
  Lately I've been finding a thorough test suite to be better at documenting code than comments. But I have to chuckle at "self documenting" every time I hear it.

sambe 10y ago

This pre-supposes a team of people who care about technical debt. I remember Eclipse in the early 2000s was already doing this (FIXME, TODO and something else IIRC). In my experience there are lot of productive programmers who, overall, add value (stuff gets done, it's not a bug-infested disaster) but simply don't care. Might not even have heard the expression technical debt. Might care more about short-term reputation wins from Getting Stuff Done. They aren't going to leave TODOs.

johnfn 10y ago
If the programmers are productive in the code, as you admit, then why would they need to spend time clearing TODOs?
- sambe 10y ago
  Short-term productive.

jsdalton 10y ago

Interesting that the author highlights CodeClimate's "support" of TODO comments via the FixMe engine. The problem is that the TODOs get flagged as failures in the context of a pull request and require a manual override. The overall attitude in the tooling is TODOs as a code smell or problem vs. a solution. Maybe this is not a big deal (since you can interpret the information however you choose) but it creates cultural resistance to embracing TODOs. We've recently started dabbling with TODOs again on my team but I still haven't overcome a bit of guilt I feel, like maybe "I'm doing it wrong" -- even though I think TODOs are a perfect fit for highlighting small tidbits of technical debt as the author describes here.

brynary 10y ago
(Founder of Code Climate here.) This is really good feedback, which we are addressing. We're going to change things up so that by default TODO issues are emitted as "Info" severity instead of "Minor", and we are going to change our PR integration so it does not fail PRs on "Info" issues. As an aside, on Tuesday we launched a Grep engine, which is much more powerful than FIXME: https://codeclimate.com/changelog/58ecfa297705a149790008b2 https://codeclimate.com/changelog/58ecfa297705a149790008b2 It allows full customization of the emitted issues.

reledi 10y ago

My advice is to never place TODO comments in your code. It will become a graveyard for TODOs and annoy fellow programmers who come across it for years after it was written. Instead 1. Quickly experiment with refactoring but stop if it feels wrong. We often underestimate how quickly we can improve the codebase. It's often better to try something quickly than waste time planning to do it. 2. Defer if it's a big refactor or you're on a very tight deadline. Write a reminder in your physical notebook so you don't prematurely pollute your board. If it feels high priority after that and you still haven't had time to do it, then make a chore ticket for it.

Normal_gaussian 10y ago
I completely disagree Placing TODO and ASAPs in code helps ensure you don't leave any loose ends, and if you call another developer onto your feature branch allows them to get a feel for how you're getting on and how complete the code is. Using a physical notebook distances the workload from the code and hides the fact something is incomplete from others. A TODO graveyard can be prevented when you review the code - a developer who thinks a feature branch littered with TODO annotations is complete code is either dreaming up future use cases or failing to complete the work assigned.
- pepve 10y ago
  I think you're both right. It's okay to have them locally or on feature branches for communication and note taking purposes. But they should never live for any prolonged time in your production code.
- TeMPOraL 10y ago
  I'm with you here. > Using a physical notebook distances the workload from the code and hides the fact something is incomplete from others. Exactly. In fact, I use both (except the notebook is an org-mode file, not a dead-tree book). TODOs / FIXMEs in code are for things very context-dependent and connected to code, for which it's important to see them in surrounding context. In more abstract cases, I just log a task in my notebook, to be done later. Examples of both - code: //TODO resourcify (i.e. move to external string resources database later) vs. notebook: ** TODO Refactor the refactor of the SomeClass class. -- Also, often TODO / FIXME comments serve for me as anchors in some larger refactoring processes. I tend to label them specifically for easy grepping (e.g. with unique Unicode chars like ). The point is, refactoring process may take few days, during which I also may need to do some other tasks, so whenever there's a piece of code that needs to be redone but not right now, I tag it for later; I can then use grep/IDE search to check if I didn't miss anything.

stuaxo 10y ago

I've been doing this for a while, you need to be sparing with it though.

TeMPOraL 10y ago

My way is simple - I occasionally grep the whole codebase for "TODO", "FIXME" and "HACK", and review the results, trying to either immediately fix them or turn into actionable items. At my $dayjob I do Java, for which the IDE also lets me conveniently view the TODO/FIXME entries. I also have Sonar, which reminds me of them through low-importance warnings.

jbernardo95 10y ago
This tools helps you with that process https://github.com/ahmadassaf/code-notes https://github.com/ahmadassaf/code-notes
- TeMPOraL 10y ago
  Thanks for the link, it looks nice. I'll consider it if I ever start doing anything in Node. At the moment, however, I prefer it simple: In Fish Shell I have: function grp grep -rni $argv end and I simply do "grp todo", "grp fixme", etc. Example output (it's actually also colored): src/main.lisp:63: ;; TODO FIXME introduce at some point a mapping for page list -> generation function, or something. src/main.lisp:89:;;; FIXME deprecated src/main.lisp:94:;;; FIXME unused and probably throwaway src/site-components.lisp:9: ;; FIXME use some page structure map to map from (name language) to base filepath src/site-components.lisp:31: (let ((colorize:*css-background-class* "no-paren-fx")) ;FIXME make configurable maybe? That's good enough for me :). Also I have appropriate highlights set up in editors & IDEs I use :).
  - PerfectDlite 10y ago
    IDEA has separate TODO tab, which can also display TODO regarding your scope - e.g. your current changes.
nobodyorother 10y ago
IIRC, most Java IDEs also natively support XXX as an alternative to HACK. "sed 's/HACK/XXX/g'" to the rescue?

luke-stanley 10y ago

To find the todos I can do: git grep -EI "TODO|FIXME" Then if I want numbers I can do: git grep -EI "TODO|FIXME" |wc --line Credit to https://www.commandlinefu.com/commands/view/12842/get-a-list-of-all-todofixme-tasks-left-to-be-done-in-your-git-project https://www.commandlinefu.com/commands/view/12842/get-a-list...

ziikutv 10y ago
Same, but I use AG.
- softawre 10y ago
  Same, but I use rg.
  - rok3 10y ago
    Same but I use: cat | Mk1 eyeball In all seriousness, the great thing about a standard like this is that it is tool agnostic.

jwineman 10y ago

A good way to minimize technical debt is to block PRs that have TODOs until the author completes them, therefore eliminating the technical debt they would have otherwise introduced.

crusso 10y ago
Although I wonder how much self-censorship that encourages. Whether or not to put a TODO in your code is a judgement call. If you tell some developers that admitting to a TODO means that they can't submit, they might not admit to them as often. It's a bit case-by-case, but I think I'd rather encourage contributors to admit to the lacks in their code and accept them - but get them to commit to follow ups that will fix the problems.
DenisM 10y ago
You're killing the messenger.
abraham 10y ago
This is likely to lead to developers just leaving out the TODOs instead of doing the work. Especially for work that isn't needed now but should be done at some point in the future.
bobbytherobot 10y ago
You aren't blocking technical debt, you are simply blocking TODO comments.
aero142 10y ago
How's that job you work at without deadlines and where engineering is the most important department?
softawre 10y ago
You should go be a team lead, get some deadlines - and the perspective that comes with it.

tchaffee 10y ago

I thought this technique was such common knowledge that I kept waiting for the punchline in the article. It was a good reminder that even the simple stuff deserves to be written about and revisited every so often.

cjhanks 10y ago
They were even written as a PEP nearly 12 years ago. https://www.python.org/dev/peps/pep-0350/ https://www.python.org/dev/peps/pep-0350/
- metaobject 10y ago
  It appears that the status of that PEP is "rejected".
temp246810 10y ago
The author mentions this themselves: >>>The great thing about TODO comments is that, as a very old programming trick, they are already supported out of the box by most tools IntelliJ, SonarQube, Rails, CodeClimate and I guess many others. Only one day after I refactored to TODO comments, a team mate fixed one that had appeared in his IDE’s TODO tab

NicoJuicy 10y ago

I thought this was only in Visual Studio, guess i'm wrong. PS. In VS - Go to View: "Task List", it gives an overview of all TODO's.

matwood 10y ago
Intellij also has this functionality. I use it as a task list when working on features that span different sections of a project.

peterwwillis 10y ago

A lot of hate for TODO/FIXME in the comments... We've been using them successfully in open source for decades. I would never rely on them between releases, but during active development of a single release they are handy. A single line is not enough to explain work needed to be done or getting said work done, but it can be enough to explain existing work, sometimes.

gtrubetskoy 10y ago

I like the way the Golang team handled the introduction of Contexts. Adding them required a lot of re-thinking, and so they added a Context.TODO() method which returned a context stub essentially. Something similar could be used with todo comments in general, e.g. in your favorite language something along the lines of: import todo todo.add("Fix this later") Which would keep track of those and you can somehow automate reporting, various restrictions and what not. [1] https://golang.org/pkg/context/#TODO https://golang.org/pkg/context/#TODO

Cerium 10y ago

I've been taught to keep these out of production code. If your code fails in a way that gets you in a lawsuit you won't want to be explaining what that "TODO: looks like a xxx here" means to the judge.

crusso 10y ago
Maybe if you're coding the algorithm for when to deploy airbags or something similarly life-protecting - but many of us are just coding todo list web sites and the next social media app. As much of a rule-follower as I am... I think that if I always had to code for the eventual lawsuit, I'd quit coding.
Ensorceled 10y ago
I guess you don't file bug reports either?
- Cerium 10y ago
  We file bug reports and fix the bugs, but we are not allowed to ship a faulty product to our customers.
  - TheCoelacanth 10y ago
    Then you must either have NASA level QA or never ship a product. Most software companies can't afford either of those.

bobbytherobot 10y ago

You can pair the TODO with the issue tracker. // TODO(<Issue Number>): <Short message>

mnarayan01 10y ago

More in reference to the comments here than the actual article, but TODOs in the comments can be used to transmit what I find to be useful information: $THING was on the writer's radar, but $THING is not handled (correctly or not) in some non-obvious manner. If your project uses them to indicate e.g. things that can not be merged into master, then obviously that's one thing, but when they're simply comments, the hate here seems misplaced. Other than (maybe) redis, I don't think I've ever seen code that did not have "potential things to do" that would have been nice to see commented.

lloydde 10y ago

In a couple of work environments, people would initial the TODO -- I'm trying to remember if Joyent is one of those companies. I liked this, because it was extra honesty about the craft and I could pick the person's brain if there were issues in that code. It would also seem to allow to get a TODO brain dump when someone is planning on leaving the company or assist in who to bring to the table for refactoring of a large component.

veneratio 10y ago
Tagging TODOs is really useful. I can always look at source control, but that's more effort than seeing a name or bug number. At Google our linters are actually configured to create errors for any TODO/FIXME that isn't immediately followed by a user id or bug number: e.g. TODO(12345) or TODO(myname). I thought it was a little annoying at first, but over time I've realized how much faster it is to have that additional context.
- dmi 10y ago
  I think it's important to highlight that it's definitely about context rather than ownership when adding a name or bug number to a TODO comment. "// TODO(dmi): update after moving to Java8" doesn't necessarily mean that it's _me_ that has to fix it, but that someone can come to me and say "Tell me more about this". This took me a while to learn/remember, but it's very helpful. The hardest part for me to keep in mind was that someone else's name on a TODO shouldn't mean I ignore it.
jwhitlark 10y ago
I've found that a time stamp is super useful in TODOs, etc.
- WorldMaker 10y ago
  Timestamps and Users that added TODOs should be available from the praise/annotate/blame tools of your source control system.

gregshap 10y ago

I see TODO's in production code as only somewhat better than commenting out 'almost working' code. It helps me understand the original intent of the developer, but I don't trust that it's actually the right thing to do, and mostly shouldn't be there.

iopuy 10y ago

The best solution I have found is to use TODO (so it is grep-able) but then add a colon followed by your initials. E.G. //TODO: JTF, Use new error handling strategy here This way it is clear who put it there and makes it MUCH easier to keep track of your debt and not your buddies.

OJFord 10y ago
Or just `git blame` the line?
- iopuy 10y ago
  No, this will take into account any changes in spacing which are legit changes that sometimes need to be made but have no effect on the logic of the commented routine.

snird 10y ago

In my opinion, this is a bad practice. 1. It prevents discussion. Whomever wrote the "TODO" solemnly decides what is there "TODO", without the ability to discuss options. 2. It does not allow prioritization of tasks easily. 3. You need yet another tool to discover issues. 4. It prevents ownership of an issue. All those issues have already been solved with a simple ticket system (github issues, JIRA tickets etc'). Why reinvent the wheel? What is the benefit here?

pavel_lishin 10y ago
> All those issues have already been solved with a simple ticket system (github issues, JIRA tickets etc'). Why reinvent the wheel? What is the benefit here? The #TODO comments live close to the code. If it gets updated (whether that's an actual fix for the tech debt while working in the area, or removing code altogether due to refactoring, there's no guarantee that the ticket will get updated - and then you spend time trying to figure out which actual tech debt tickets are up to date or not. It also means that they're easily discoverable - you can stumble on one while working on something, without having to hunt through Jira for what to fix. You're also likely to understand how to fix it without having to come up to speed, since you're already working in that code.
kbenson 10y ago
You are describing policy issues with a technical solution. The solution to policy issues such as those is to make it policy to only use the solution at appropriate times. If you only allows TODO after a discussion (e.g. TODO: We decided to forego implementing X at this time, but we may need it later, as per project lead Y). It does not prevent prioritization or ownership, and there's nothing to prevent a corresponding entry in some management system (and indeed, you can put the ID from that system in the TODO). That said, often there's things you want to signpost specifically for future developers (including yourself) which may not rise to the level of needing a ticket assigned or external tracking (or that may be complicated due to bureaucracy or or you measure goals being met). There are plenty of reasons to have an additional channel to signal information directly to a dev. Just don't make that instead off the official channels of communication without good cause.

skybrian 10y ago

TODO's are for things that are optional to fix and probably won't be fixed. Sometimes not fixing something is the right move, but you leave a signpost that you deliberately skipped it. Someone else, later, can pick it up, if they choose. Whether fixed or not, it's valuable to future readers to know there's a gap.

degenerate 10y ago
This is exactly what I use them for and it works well. They are like the "falling rocks" signs on roads. The "TODO" is to make the entire cliffside completely safe, but as long as everyone is watching for rocks when driving (coding) in this section, that suffices.
pc2g4d 10y ago
I tend to use TODO for features/functionality I'd like to add, and FIXME for existing functionality that's not doing what we want. Obviously there's a fuzzy line there.
robmaister 10y ago
I will usually also include //HACK comments with a little note as to what is broken or what my assumptions were at the time of writing, for things that I believe are likely to cause breakage later on. TODOs are for optional/longer-term things as you described, like inefficient implementations because the current assumption is that it will ever only operate on 20 elements. HACKs are more along the lines of "hey if you're debugging this bit of code, your issue is probably here"

heisenbit 10y ago

This may be a technique to support tracking of technical debt IN your source code IFF it can be attributed to a specific place. Some of the more vexing debt is across the code, in the systems around the system being build or in the tool chain and needs other types of tracking.

tonto 10y ago

One way I thought of doing this would be to just have every commit tagged with some subjective score given by the committer (in commit message), probably just 1,2,3 to avoid too much weird subjectivity of a x/10 ranking, that gives how much the user subjectively thinks a commit is janky. then you will get a map of source code quality over time

plandis 10y ago

On my team at work we require all todos to link to a tracking issue (think like JIRA, etc...) That way it's 1.) Clear what the context on the todo is 2.) It's clearly in our backlog and can be prioritized accordingly. We have some scripts that run at build time to verify all todos have the appropriate issue as well as manual code reviews on all changes and I honestly don't remember the last time it was done incorrectly.

awaisraad 10y ago

There's also // FIXME

paulddraper 10y ago

1. If you are going to write TODO, write TODO(paul) or similar, so that you easily know the originator. 2. Unless the dev team is very small, most TODOs belong in your issue tracking system. That's where they can be enumerated, described, discussed, prioritized, assigned, etc.

gumby 10y ago

I was weirded out by this line: "Some tools, IDEs in particular, tend to assume that you should fix all your TODOs before you commit anything." Holy crap that's fragile! I'm still looking for the value add of an IDE. I'm not negative toward them (I know many many people use them and get a lot of value out of them) but I personally have never found one that was easier than simply writing and compiling code. Could be my use cases (the kind of code I write/projects I do).

l0b0 10y ago
Ditto until relatively recently. Vim, Emacs, jEdit, Notepad++ until about four years ago when I tried IntelliJ IDEA. Never looked back. It was also an eye opener about the limits of tool support in loosely typed languages.
- gumby 10y ago
  I have a colleague using IDEA for the part of our project that's in Java. There's a continuous stream of curses coming from his desk and he's been programming in Java since it was first announced by Sun. Part of the problem I think is taking your hands of the keyboard to manipulate the mouse.

antirez 10y ago

The first comment in the blog post is great about using XXX, TODO and FIXME for different types of debt.

retreatguru 10y ago

I have been doing this for years. I find it helpful when going to refactor a part of the app that has problems. I then go look in the code and see TODO comments I added a while ago. Then I am 100% sure I really should fix that up. Yes they can get stale but usually they tend to be helpful. I really like reading todos written by other devs to see where a feature was left incomplete. It's so much easier to see it right in the code rather than lost in a ticketing system.

x21 10y ago

I recently finished writing my master's thesis on "the impact of self-admitted technical debt on software quality" [2], we use the same approach this article advocates to identify this type of technical debt, which we call "self-admitted technical debt" (SATD) [1]. We examined the impact of SATD on software quality for forty open-source projects. To measure this, we took into account three criteria commonly associated with quality: (i) on the file level, the relationship between defects and SATD; (ii) on the change level, the potential of SATD to introduce future defects and (iii) the complexity SATD changes impose on the system. The results of our study indicate that: (i) SATD and defects exhibit no correlation at the file level, (ii) SATD changes make the system more susceptible to future defects than non-SATD changes do and (iii) SATD changes are more difficult to perform on the system. [2] (an abbreviated version [3]) There are more patterns to identify technical debt than "TODO, FIXME or XXX". You can find the rest of the patterns here [1]. It is very interesting to see developers confessing their workarounds and hacks through source code comments, as it can alert later contributors to the technical debt induced. References: [1] http://das.encs.concordia.ca/uploads/2016/01/Potdar_ICSME2014.pdf http://das.encs.concordia.ca/uploads/2016/01/Potdar_ICSME201... [2] https://www.scribd.com/document/345197805/Sultan-Wehaibi-master-s-thesis?secret_password=Zq5b32lVkHiyitBuQ1nQ https://www.scribd.com/document/345197805/Sultan-Wehaibi-mas... [3] http://das.encs.concordia.ca/uploads/2016/01/Wehaibi_SANER2016.pdf http://das.encs.concordia.ca/uploads/2016/01/Wehaibi_SANER20...

webninja 10y ago

Meanwhile, at the Indian contracting company where I currently work, I came across a few lines of code in a phone application that no longer logged data to a log file. I was told that it had been there for a number of years. As I went to instinctually remove it, I was told by my supervisor that "we don't remove anything unless we get a Code Cleanup task". Cleaning up the code now would be "Out of Scope". It's no wonder now how this project has 1M lines of code and 10K files... Garbage in, nothing out.

Too 10y ago
Engineers who only do exactly what management tells them to do should be thrown out with the head first. If management knew exactly what has to be done there wouldn't be a need for engineers in the first place.

ascotan 10y ago

The google style guide for c++ actually has a recommended format for TODO's where the author is in parens: // TODO(author): fix this that way you know who was TODO'ing