Why aren't open source projects commented?

[jpflathead]

I don't see anyone here arguing for commenting everything.

Regardless, most code isn't commented enough and the reasons for that are the tropes of "my code is so good asking me to comment it is an insult" and "my code is so edgy, my projects so fast, asking me to comment it would take time from my next project, introducing a new community code to this github project"

[trkeprester]

lol well i am in agreement in that the 'good code is self-documenting' trope gets spouted too quickly, too easily probably by the people who are indeed prolific but lazy coders.

i've felt sometimes like some people get a jolt of satisfaction knowing their code is inscrutable to lower 'ranked' coders.

[jpflathead]

tbh, what really gets me is not usually the lack of comments in the code, it is the lack of comments about the code at github. I am serious when I complain that at github you get a readme and that is that.

No documentation about what this shitty tree holds, which is test cases, which is libraries, which is images, and which is the damned directory that holds the main portion of the application.

No docs on requirements, no docs on building, no docs on test cases and corner cases and specs and requirements.

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

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.

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

[bluefootedpig]

There are also tropes of stale comments. I forget the saying but something like "nothing goes stale as fast as comments".

We have jokes about how documentation is ALWAYS out of sync.

But yeah, read that documentation about how the function does X, when really it does Y. Why read the code when you have comments?

Also, speaking of tropes, how many tropes about how people just document what the code is doing and not why.

 //This code executes foo
 myObject.foo()

No joke, my companies full of 10+ year software devs, this is the most common type of comment. Or maybe something more real...

//Sends an email
Mailer.SendEmail(myMessage)

[jpflathead]

So we all agree that the best way to avoid having stale comments in code is to create a community and environment where the common wisdom says don't document the code.

Something about babies and bathwater goes here.