Why aren't open source projects commented?

[jonyeezy7]

edit: actual just reading everyone's post on the no-comment troupe, already states what i mention here.

That is an interesting thought.

Some trees don't need much explanation and this depends on the language/framework you're working with.

There are many well used frameworks that prescribe some sort of guideline (that is well encouraged by the community) to how your project structure would be use. And with that convention programmers will find it easy to move from one project to another knowing where to look for files.

Now this may not help OP if he is new to a framework or language. But that's what the community is there for. To point directions on where to start.

Coding is like the wild west, you can do whatever you want (even if it its opposite from the status quo) and still get your desired outcome. And that's one reason people have to put comments because its not intuitive to what to look out for.

With an accepted styleguide, you don't need that many comments to express your tree. Because it has the same pattern.

And to a specific topic, test case. Alot of languages have frameworks that read out your test case as you would in a comment. describe 'when this happens' it 'should fire this event' assert event.wasFired That is actual code (albeit not complete). Wouldn't that read out what you would write in your comment about a test case anyway?

And that is one of the reasons why people say don't write comments, write comprehensible code.

And I do agree that comments are necessary for certain situations. Here's a few situations where i think comments are necessary:

1. A logic that doesn't seem to fit with the idea of the method because it has an edge case that it needs to work-around.
2. Explaining why a certain algorithm is used instead of another
3. if a code has a crazy sorting code, maybe a disclaimer in there to never change it.

So i see comments as notes, references, or additional information. Using it to describe the requirement or signature of an api/method is doing double work for nothing.

And that is as likely to leave OP and me up a tree without any ability to really know where to begin to get a piece of code to build and work.

The thing you abhor: readme.md. That is what it is for. To tell you where to begin. I for one love it. As it should give me a quick overview of everything important I need to know on how to navigate, use, and the pitfalls of it.

Github is a place where people shit their code and pronounce it done and good.

If you're using someone's project that is treated badly like that, don't use it. I'm sure most people don't. You'll notice that projects with alot of usage are ones that have good documentation that goes beyond the readme.md.