5 ms·

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

pilif 15y ago
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.
- cydonian_monk 15y ago
  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.)
- noamsml 15y ago
  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.
- erichocean 15y ago
  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.
- why-el 15y ago
  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.
  - jakejake 15y ago
    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!
- pook1e 15y ago
  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.
lifeisstillgood 15y ago
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.
- zokier 15y ago
  Eclipse adds comments tagged with TODO/FIXME/XXX automagically to task list. Not perfect, but a nice feature anyways.
  - finnw 15y ago
    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.
kinow 15y ago
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+Plugin https://wiki.jenkins-ci.org/display/JENKINS/Task+Scanner+Plu... Cheers
powertower 15y ago
"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.
steve8918 15y ago
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.
motter 15y ago
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.
chj 15y ago
some TODO is left as todo, because it is hard.
msluyter 15y ago
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?
- riledhel 15y ago
  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.
pbreit 15y ago
None of the arguments against the OP are very compelling.
scottshea 15y ago
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
jmathai 15y ago
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&sort=created&direction=desc&state=open&page=1 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 http://theopenphotoproject.org/contribute
xbryanx 15y ago
How to contribute to an open source project: write documentation!
- markrickert 15y ago
  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.
  - zafka 15y ago
    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.
  - mfringel 15y ago
    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.
  - silentbicycle 15y ago
    Are there any particularly skilled documentation/technical writers in open source? They aren't getting enough recognition.
- angersock 15y ago
  This a million times. I could care less if the code has a weird cornercase TODO, as long as that gotcha is documented!
kingkilr 15y ago
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.
- freehunter 15y ago
  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.
- rhizome 15y ago
  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?
  - Arelius 15y ago
    Then they probally are not the kind of person That would require a HN article to tell them what code to work on.
    - rhizome 15y ago
      What does that say about the people participating in this thread?
      - Arelius 15y ago
        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.
        rhizome 15y ago
cpeterso 15y ago
* 2,630,760 FIXMEs https://github.com/search?type=Code&q=FIXME 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 https://github.com/search?type=Code&q=TODO
raymondh 15y ago
If someone is looking for open source work in Python, the IDLE editor could use some love and care :-)
- sho_hn 15y ago
  Would a Qt port fly?
  - mkl 15y ago
    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 http://code.google.com/p/spyderlib/wiki/NoteForContributors
    - sho_hn 15y ago
      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.
callahad 15y ago
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.
- nicksergeant 15y ago
  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.
  - riledhel 15y ago
    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.
  - jakejake 15y ago
    I wouldn't get too upset over dissenting opinions, that's partly what makes for great conversation here!
Jayasimhan 15y ago
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".
joelhooks 15y ago
Adding unit test coverage is another great way to contribute.
INTPenis 15y ago
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.

pilif 15y ago

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.

cydonian_monk 15y ago
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.)
noamsml 15y ago
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.
erichocean 15y ago
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.
why-el 15y ago
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.
- jakejake 15y ago
  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!
pook1e 15y ago
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.

lifeisstillgood 15y ago

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.

zokier 15y ago
Eclipse adds comments tagged with TODO/FIXME/XXX automagically to task list. Not perfect, but a nice feature anyways.
- finnw 15y ago
  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.

kinow 15y ago

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+Plugin https://wiki.jenkins-ci.org/display/JENKINS/Task+Scanner+Plu... Cheers

powertower 15y ago

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

steve8918 15y ago

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.

motter 15y ago

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.

chj 15y ago

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

msluyter 15y ago

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?

riledhel 15y ago
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.

pbreit 15y ago

None of the arguments against the OP are very compelling.

scottshea 15y ago

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

jmathai 15y ago

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&sort=created&direction=desc&state=open&page=1 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 http://theopenphotoproject.org/contribute

xbryanx 15y ago

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

markrickert 15y ago
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.
- zafka 15y ago
  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.
- mfringel 15y ago
  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.
- silentbicycle 15y ago
  Are there any particularly skilled documentation/technical writers in open source? They aren't getting enough recognition.
angersock 15y ago
This a million times. I could care less if the code has a weird cornercase TODO, as long as that gotcha is documented!

kingkilr 15y ago

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.

freehunter 15y ago
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.
rhizome 15y ago
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?
- Arelius 15y ago
  Then they probally are not the kind of person That would require a HN article to tell them what code to work on.
  - rhizome 15y ago
    What does that say about the people participating in this thread?
    - Arelius 15y ago
      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.
      - rhizome 15y ago

cpeterso 15y ago

* 2,630,760 FIXMEs https://github.com/search?type=Code&q=FIXME 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 https://github.com/search?type=Code&q=TODO

raymondh 15y ago

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

sho_hn 15y ago
Would a Qt port fly?
- mkl 15y ago
  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 http://code.google.com/p/spyderlib/wiki/NoteForContributors
  - sho_hn 15y ago
    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.

callahad 15y ago

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.

nicksergeant 15y ago
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.
- riledhel 15y ago
  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.
- jakejake 15y ago
  I wouldn't get too upset over dissenting opinions, that's partly what makes for great conversation here!

Jayasimhan 15y ago

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

joelhooks 15y ago

Adding unit test coverage is another great way to contribute.

INTPenis 15y ago

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.