Judging by the nature of the TODOs left in both my open- and closed source code, I'm not convinced that this is entirely good advice.
Usually the reason for me to leave a TODO is when something really minor doesn't work right and making it work would more often than not be a huge undertaking or at least require quite a bit of thought.
If the thing that didn't work right was important, I'd add a bug to the tracker in order not to forget it. If it was easily fixable, I'd fix it then and there.
This leaves these TODOs to be tasks I would not want a newcomer to the code base to tackle, because the first solution they would come up with is likely incorrect, so all the amount they'd put into fixing it might end up in vain.
That said: maybe others use TODOs differently. This really is judging from my own experience.
You're not far off of how we work. TODOs end up in two categories: minor things I need to do before a commit, and major things that require some huge chunk of code to be [re]written but maybe aren't "features" and don't need official documentation. We see the latter more often in new products and not in mature codebases.
(Then there are the orphan TODOs - such as one strange ??TODO?? in some code I inherited that has no good documentation (just a vague reference to another class) but looks too important to remove. One of these days it's getting deleted.)
I know when I write TODOs, it's usually because my solution isn't clean or misses an irrelevant edge case that may become relevant if requirements change.
I generally use "FIXME" if it's actually something that needs to get corrected. TODOs are more like you describe -- nice to haves (perhaps), but too much work for the benefit.
Well something really minor is exactly what the students we was talking about are looking for. This is excellent advice for me, since I am new to web development and usually get so intimidated by the cheer volume of code I am exposed to that I abandon it.
I think he is saying that TODO are often not that simple because many programmers use them for something that works, but needs a conceptual change - which can be a major task.
It depends on the project though. Other projects may rely more on an issue tracker.
Either way, don't let it stop you, most open source projects are glad to have help!
True, but I think it can go both ways. I've used TODO a few times just to remind myself about something fairly trivial that I didn't feel like compiling/testing again before I commit (ie. cleaning up code, small optimizations, etc.)
I think the general advise in this article is good, though. By searching TODOs, I'm sure there will be many non-trivial fixes that will be found. But at the same time, I'm confident that it's a good way to find little things that have been forgotten about in the code.
I'm kind of surprised by all of the nay-saying. I'm sure a fair number of my TODO or FIXME comments involve things that are, in fact, tractable. To check myself, I just grepped through some in-development code, and the following TODOs sure seem approachable:
TODO: Add "busy" indicator while waiting.
TODO: Ensure that :foo_url and :bar_url parse.
TODO: Assemble absolute URL based on :foo_url if :bar_url is relative.
TODO: Verify that this is one of the user's foos.
TODO: Use protocol relative address in production.
TODO: Dynamically set hostname based on environment.
TODO: Document these; especially their options!
I mean, sure, I should fix them. And I will. But I haven't gotten around to it yet.
Unfortunately, the naysaying on HN is getting to the point where I read the first comment (usually someone bitching and/or disagreeing) and get fed up and leave.
I understand you completely, so nowadays I try reading the second and third comments before leaving. Sometimes the very good comments end up buried in a mess; we might need a way to highlight those with a lot of votes somehow.
Documentation done right is a real joy. Of course to do it right, one needs to completely understand what is going on. It takes some real discipline to get to that point, and then not skip to more exciting things.
While this is true, there's not much of a positive feedback loop on doing documentation. At best, you get a nod and a vaguely wary glance reserved for people who memorize the telephone book.
We've been trying to make it easier for newcomers to contribute to The OpenPhoto Project. The approach we're taking is to identify issues and label them as "Beginner". These issues are ones which have very little probability of breaking some other component in the system.
In addition to that we're working on creating the unit test for the contributor to uncomment before checking the fix in to verify that it does in fact do what we had intended when creating the issue.
We've also set up a contribute section on the site to help. I'd really love to know what more helps new developers that want to start contributing to an open source project.
Why do this when you can simply look at an issue list?
Seems likely that an issue entry will provide better context to the problem than a simple TODO would. Issues may also be tagged with a rough indication of how much work they will require to tackle. Choosing issues that are a small amount of work seem to be a good way to get familiar with a codebase.
One thing that I plan on doing after I've finished my current batch of subprojects, is to go to the project's bug database, and start fixing bugs. If I join a new company, that's probably the first thing I'd be working on as well, so it's good practice, and the easiest way to get familiar with the codebase.
There's also the Python plugin for KDevelop, which probably offers the most sophisticated semantic support for the language today, now beating Wing and MS in its level of type inference abilities, type tracking through containers, etc. So yes, a Python IDE using Qt is nothing new. But IDLE is simple and bundled with Python, so it serves a special role. I see it more as a teaching tool than a production-grade environment. It's just that having to work with the crummy Tk toolkit when hacking on it is a major turn-off.
This is really bad advise. If I commit a TODO to my code, it's because the difficulty of fixing vastly outstrips the value of fixing it. If it was an easy thing to fix, I'd have done it myself.
If I commit a TODO to my code, it's because the difficulty of fixing vastly outstrips the value of fixing it.
Here we see the Dunning-Kruger in its natural habitat. What if someone is a better programmer than you? What if that person is a random internet foobar who finds your code and wants to contribute?
I agree that you may get smart people coming up with great solutions, but the article seemed to be aimed at beginners looking for a way to contribute.
The complexity of TODOs in code depends entirely on the style of the person who put it there. In my case TODOs are usually things that are going to require some refactoring.
Maybe we need a standard on what TODO or FIXME is meant for. Personally (as a non-professional coder) I put TODOs out there to remind myself or someone else what I have planned for the future. TODO contains everything that I will do very soon but haven't gotten around to doing yet.
This is one of those times when I read just the title and smack myself in the head because it was so obvious I missed it. Sure not all of the TODOs will make sense to me but it at least helps
Related question: I've been wanting to find a small (ruby/rails) project to get involved in. Github gives you a nice view of large/active projects, but it's sort of hard to find something that is smaller and (in theory) easier to get up to speed on. I know the standard advice is to find something that you're using that interests you, but I'm new enough to rails that I just don't have enough background to know what that might be. Any other suggestions?
You can start a project based on RoR to highlight those small projects on Github. I don't know what metric could be useful to find the interesting ones though.
What we can get out of this is post is that there is a lack of common protocol between the existing contributors and new ones who want to jump in. If TODO is not the right fit, then something like a FIXME or TESTME should help the new developer get started quickly. If a project follows this protocol, just add notes in the contribute section of the Readme; something like: "New contributors can get started with looking for FIXME in the code base".
This is why TODO lines should have a common format so you can grep for them easily. I for example can grep all my TODO's and > straight into a TODO.md file and have a near instant markdown unordered TODO list.
Vim even highlights TODO: in my code and it always starts with some type of comment on a line of its own.
Don't forget XXX, fix this and a variety of swear words in different languages
I have written two or three apps over the years that parse source code for this and others, but nothing ever satisfying really felt right. If anyone has something perfect do shout.
But does anyone use the task list? I never have, and have never found such a thing necessary. My "task list" consists of the following (in order):
* Compiler errors
* Unit test failures
* Compiler warnings
* FindBugs warnings
* Bug tracker
The IDE already highlights the first four, and for all but #2 it tells me what source line to look at, so I don't see much potential benefit from using the task list.
Having said that I do use XXX tags, but just for the syntax highlighting.
Usually the reason for me to leave a TODO is when something really minor doesn't work right and making it work would more often than not be a huge undertaking or at least require quite a bit of thought.
If the thing that didn't work right was important, I'd add a bug to the tracker in order not to forget it. If it was easily fixable, I'd fix it then and there.
This leaves these TODOs to be tasks I would not want a newcomer to the code base to tackle, because the first solution they would come up with is likely incorrect, so all the amount they'd put into fixing it might end up in vain.
That said: maybe others use TODOs differently. This really is judging from my own experience.