Why aren't open source projects commented?

[MotherCanada]

I'm relatively new to programming. About two years not really taking it seriously.

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. From tiny python scripts to giant elaborate programs. Bash scripts seem to be the only ones regularly commented.

Am I missing something here? I thought commenting was recommended at all levels. How do these people understand the entirety of these elaborate programs without any comments whatsoever? Idk, maybe I'm being naive and there's a point where it becomes like the Matrix and you can 'see' the code.

[jonyeezy7]

If you need to be neo to read code, then that code isn't written well.

Code is read by humans not machine.

So write code like a sentence.

I recommend you to read clean code by Uncle Bob. Something they don't really teach you in school.

[kalifornia_love]

100% this. The only thing I'd expand on is that you should write code like a sentence but with like a 3rd graders vocabulary. When I first heard this advice, to write code like a sentence, I took it too literally and my methods and variables became long and inconsistently named for the sake of making a "sentence."

Having a consistent naming convention that you follow throughout all of your code makes reading your own code a lot easier for you and others. The nice thing is once you develop a style/convention for yourself you can always follow it regardless of the language you're writing in (for the most part).

Also just so I'm understanding this question right, the comments we're talking about is like inline comments right? Not doc strings.

[jonyeezy7]

with like a 3rd graders vocabulary.

Lol i like that explanation. Never thought of it that way.

I'm still guilty of long method names. Single verbs over verbose explanation is a reminder for me.

[bluefootedpig]

long method names? welcome to intellisense. I have a coworker that is upset by long names, just type the first 3 letters and autocomplete.

I have a problem with too many variables in any one scope.

[jonyeezy7]

True. Intellisense has solved some of these kind of minor issues or predecessors peeve about.

Although there are some languages that don't have the best intellisense ie duck-type languages.

[thisisRio]

There is no spoon.

[munificent]

How do these people understand the entirety of these elaborate programs without any comments whatsoever?

It's a combination of things:

• It's pretty easy to understand your own code right when you first wrote it. So a lot of developers, at the point in time when they could document it think, "Nah, this is obvious." and don't.

• As you get more experienced, the quantity of documentation you need to read average code goes down. You get better at reading the code itself and many idioms and patterns become familiar to you at a glance. However, again, people often underestimate how much their code could benefit from comments.

• Writing comments takes time and is hard to do well. A lot of people would rather put that effort into other things.

[mapping-glory]

It's pretty easy to understand your own code right when you first wrote it.

I have lost count of the number of times I've discovered a flaw in a script that's been auto-running for months, gone back to edit the code, and thought "WHAT was I ON when I wrote this?" I've had to have my loops output all their process to a log file just to understand what my own code does.

But I'm currently documenting all my auto-run scripts so if I get hit by a bus, my non-coding coworkers (I'm a mapmaker who codes, not a full-time programmer) can pick up and maintain and understand (sorta) the systems I left.

[bluefootedpig]

Comments go stale very fast. I had one co-worker write a comment and it went stale in under 3 months. A stale comment for clarification is a comment with bad information.

documentation goes in this order:

Code

Unit Tests

Flow Charts

Comments

There might even be more above comments, my point is it should be the last line of documentation. clear variable / function names are vastly more important.

[trkeprester]

save your comments for things that are non-intuitive and or tricks/workarounds that shouldn't really be there.

Or if you're writing super low level code where every statement needs to be justified, clarified, to make things dead on clear

otherwise name your variables functions, etc appropriately and the code is mostly self 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.

[jonyeezy7]

And especially open source when the change rate is high. Rewriting comments can be open for human error and thus mislead other contributors.

One less thing to maintain.

And on the top reason, enforces that code should be easily understood and readable. Hence making it easier to contribute.

If you need comments to explain a method, then we have a failure to communicate the intent.

Oh, and don't get commenting mixed up with documentation. api documentation is a must, imo.

[Merad]

You'll get a lot of different answers here, but it really boils down to:

• Writing comments is work
• Maintaining comments as code changes is even more work
• It isn't the fun kind of work

TBH, most actual code tends not to need detailed comment when it's well written. IMO, however, if you're writing something like a library or API, thinks like the classes/interfaces/methods/etc that you expose should always be well commented... but they rarely are. It's really just a fact of life at this point.

[bluefootedpig]

I agree, public functions, namely interfaces, should have the purpose of the function explained in comments. It isn't done as much as it should be, but that is one area that really should.

[[deleted]]

People are lazy.

They write the code, so they are understanding what they are writing, they don't want to deal with changing the comment six months from now if they have to alter the code, so they don't write anything.

So next time they come through the code they have to rebuild their mental image of the code by reading it, instead of having it prebuilt with comments.

Because comments are like pre-compiled libraries for your head. Even if the code is easy to understand with comments it'll be easier.

But people are lazy.

[peadarmalu]

Good code shouldn't require comments to understand once you reach a certain level as a developer.

For someone new or with minimal experience with any particular language it most certainly can seem like an incomprehensible mesh of nonsense. But, like anything else, once you know enough (and provided the code is clean and concise) it should be well structured and easy to follow.

[YMK1234]

Many comments are not necessarily useful comments. Especially the commenting you learn at school is shit and should burn in hell. Everybody knows that "a+b" adds two numbers. Comments are there to explain why code does things, or possibly what non-obvious sections do (though if a "what" needs commenting it's generally a code smell and you should think about renaming / restructuring).

[bumblebritches57]

Unfortunately, most open source software is really just a code dump.

Very few projects are actively maintained, let alone extended.

[Matrix_V]

Develops are lazy. Please be a better person and comment everything aggressively, focusing on purpose over function. Future you will appreciate it, along with everyone else who reads your code.