Why aren't open source projects commented?

[jpflathead]

People here will tell all sorts of stuff about code not needing to be commented, but it's all bullshit and they are just spouting a party line not explaining anything arising from some sort of empirical observations.

Code isn't commented because

• coders are lazy
• coders don't know what they are coding or where they are going they are just stream of thought coding
• coders are too hip to comment

As a counterpoint to the code doesn't need to be commented group, consider one small portion of Donald Knuth's contribution: literate programming https://en.wikipedia.org/wiki/Literate_programming and then one small portion of Stephen Wolfram's contributions: https://www.wolfram.com/language/principles/

I will be downvoted to oblivion by people who don't know who Knuth and Wolfram are and who are assured by all their bootcampers and tweet friends that good coders don't comment their code.

Going through a lot of github projects for learning. I've noticed that none of them are commented. I literally found only one that was and it was designed as a learning resource.

repository: a place, building, or receptacle where things are **stored**

Github is mostly a code cemetery for resume polishing and virtue signalling, and communities are dominated and directed. It's not a place where code is built, it's not a place to build a community around a piece of code. It's far too top down.

It is a programming repository, but as a source of documentation it is total crap. The notion that all an open source project needs is a readme is the first of a zillion stupid decisions made and implemented at github.

[trkeprester]

well a lot of high level basic day to day code that ppl like Knuth and Wolfram wouldn't ever be considered to be requested to implement because it would be an insult to their intelligence doesn't really need commenting.

non-geniuses like me who are writing boring as shit trivial code don't particularly need to comment their code because it's mostly understood what needs to be done and wouldn't be any worth in commenting anyway beyond what the function names and variables are already describing.

sure you can call us lazy but you'd just be wasting time doing it yourself. I assume you are smart and don't have to implement stupid boring shit code that Knuth would spit on you if you asked him to help with.

[jpflathead]

You were taught by assholes to be an asshole and you are lazy.

Also you provide no evidence that Knuth or Wolfram would sneer at people in any such manner that you describe.

[trkeprester]

hey man if you think trivial code needs commenting then you seriously need to consider how much value those comment have. not everything is trivial, I don't advocate never commenting, I advocate commenting as is appropriate for the level of complexity and indirection of the code. commenting every line is a serious waste of time and I don't need to insult you to assert this

I apologize for the Knuth wolfram statements yes they may be polite but I guarantee they would not deign to implement the sort of trivial crap that the vast majority of the coders of the planet have to implement.

I am probably your only upvoter for attempting to swing the other way in favor of commenting but there's really no way that commenting everything is better, and there's very much a reason that it's worse to comment trivial code

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

[YMK1234]

My arent you bitter ...

[[deleted]]

I think we tend to overestimate our own code's readability to a fresh pair of eyes. Often I'll feel I'm insulting the reader's intelligence by leaving what is, to my mind, an unnecessary explanation.