How to contribute to an open source project: look for TODOs in code | Hacker News Reader

How to contribute to an open source project: look for TODOs in code

ivanzuzak.info

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.

I wouldn't get too upset over dissenting opinions, that's partly what makes for great conversation here!

How to contribute to an open source project: write documentation!

Wish I could upvote this. Inner more than once.

Documentation is the last thing to get done (if at all) and the least glamorous, but it needs to be done.

This is especially easy to do if the project has a wiki.

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.

Are there any particularly skilled documentation/technical writers in open source? They aren't getting enough recognition.

This a million times. I could care less if the code has a weird cornercase TODO, as long as that gotcha is documented!

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.

https://github.com/openphoto/frontend/issues?labels=Beginner...

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.

http://theopenphotoproject.org/contribute

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.

"How to contribute to a small open source project: look for TODOs in code" would probably work better for anyone looking for this type of advise.

Fixing even minor details in large (and complex) projects can require for you to understand all the details of that project.

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.

If someone is looking for open source work in Python, the IDLE editor could use some love and care :-)

Would a Qt port fly?

There's already Spyder, so I'm not sure how much value that would add. Plus, Spyder is still fairly new, so it's probably easy to find things to do there: http://code.google.com/p/spyderlib/wiki/NoteForContributors

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.

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.

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?

Then they probally are not the kind of person That would require a HN article to tell them what code to work on.

What does that say about the people participating in this thread?

In fact, it says very little. The very fact that they are commenting on it generally suggests that they don't take the article as fact.

That seems like a bit of a leap.

Regardless, I don't think that my original comment applies simply due to someone participating in this thread.

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.

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.

None of the arguments against the OP are very compelling.

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".

* 2,630,760 FIXMEs https://github.com/search?type=Code&q=FIXME

* 8,082,861 TODOs (though some of these are to-do apps <:) https://github.com/search?type=Code&q=TODO

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.

Eclipse adds comments tagged with TODO/FIXME/XXX automagically to task list. Not perfect, but a nice feature anyways.

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.

Commented at Github, but will leave the link for the plug-in in Jenkins that I use to scan open tasks here too.

https://wiki.jenkins-ci.org/display/JENKINS/Task+Scanner+Plu...

Cheers

Adding unit test coverage is another great way to contribute.

some TODO is left as todo, because it is hard.

Reply on news.ycombinator.com