Working in an open source project has the result that sometimes developers with no experience in the codebase attempt to "learn the code" on their own.

There is a reoccurring trap I've seen, where new developers try to:

understand everything before doing anything.

These tend to be developers who only ever worked on their own projects, or at least smaller codebases, where this may work out OK.

My impression is that they try to read the code a bit like it's a book, hoping that somewhere near the end they will have an "ahah" moment where they will understand it and start writing new code and being productive.
(I'm simplifying a bit here).

This always seems to end badly.

Rather than questioning their approach, they complain the code is confusing and needs more comments.
(Whether or not to include comments is a big topic. For purpose of discussion we can assume the code is reasonably well-commented.)

Not to suggest the code is perfect either, but some developers manage to learn it and become productive.

To me the approach is flawed to begin with, but asking since this is such a common assumption/mistake.

When developers have already tried and failed to enter a large codebase by reading over the code:

What steps might an open-source project take to help new developers avoid common pitfalls based on (often poor) assumptions?

Note on the "volunteers for open source" aspect (added for clarification)

You might think that the volunteer part of the question isn't important and that any new developer on a large codebase would run into these problems.

While this may be true in some cases, there is a difference that volunteers aren't employed by the organization, they can do what they like, how they like - and may do a significant amount of work on their own without asking for guidance, further, they are free to ignore all advice too. Even if their work is rejected for example, they may continue to develop it, start a fork etc....

This typically isn't the case a developer employed to work on closed source software.

  • A very good question here, but I'm voting to close as too broad as the boldfaced question doesn't seem to be specific in nature.
    – Zizouz212
    Jun 23, 2015 at 21:24
  • 1
    Understood, this is a soft question (as in soft-skills), yet there are some examples of this for common issues people face on projects - eg: programmers.stackexchange.com/questions/197650/…
    – ideasman42
    Jun 23, 2015 at 21:29
  • I understand, but it's that this question is still very broad. It could help to place a situation or something to help people, or it will likely get closed...
    – Zizouz212
    Jun 23, 2015 at 21:31
  • @Zizouz212, Updated boldface question, though it does remain rather broad.
    – ideasman42
    Jun 23, 2015 at 21:37
  • possible duplicate of opensource.stackexchange.com/q/54/40 Jun 23, 2015 at 22:04

1 Answer 1


Write a wiki / documentation on the code that's already developed.

Considering you have a large amount of code, document it. If I were looking to volunteer, the first thing I'd do is learn the structure of the code and how to use it if I don't already.

Write a short guideline on what you're expecting from contributes.

More simply, just write guidelines. It's a common practice on platforms like GitHub to create a CONTRIBUTING.md file, which outlines some expectations and guides the user to how to contribute.

Have the code-base commented where it's need.

Comment your code to help incoming contributes understand each individual bits that may appear confusing. Comments in their name are pretty much self explanatory.

Not the answer you're looking for? Browse other questions tagged or ask your own question.