i looked over the source code for Bosque. Hardly any comments. Code is for computers, and comments are for people (including the author who months down the road may not remember why something was done). Maybe in big companies you can slip through the cracks. I was also surprised that Boeing bungled the software so bad for the MCAS system, a critical system that only read one of 2 sensors, and had numerous fatal - as in killing people - mistakes in their software. I sure hope that all the designers here make an effort in your new language to encourage people to comment their code.

I've worked on large code bases were comments were explicitly banned, or at least discouraged. There are other ways to communicate the intent of code that are better than comments though. This code base used a lot of runtime asserts to validate assumptions, and they often had messages, so they were comments of sorts. Integration and unit tests with good coverage are better than comments. I know that for a lot of people the answer is "do everything!" but there is a cost to that as well.

I have mixed feelings about comments. For one thing, inline comments are certainly limited ... I'd rather have literate programming with full support for graphics, typesetting, sectioning and so on. But, I also think that there's some wishful thinking when it comes to code documentation. "If only this were documented better, people could understand it with little effort." The reason I think this is wishful thinking is basically the counterexample of TeX - a program that is meticulously documented in a printed book with extensive tests, examples, a companion book giving a high-level overview. All this effort seems to have failed to make it comprehensible. TeX code is rarely adapted to other purposes, people even want to rewrite TeX or extract the core algorithms into other languages. The lesson I take from it is that a large, dense code base can not be understood at all without extreme effort. Unless it is someone's job or serious project to understand it, they will not do so no matter how well commented it is etc. If it is someone's job to understand it then they will be glad for the comments but it will still be a huge effort. So I think comments/documentation are important, but far less important than simpler, smaller code bases.

Tex is one of the worst systems ever devised. The Eve project adopted markdown as the commenting system, and i think that is a reasonable way to offer graphical commenting without a lot of baggage. The idea of banning comments in a large code base is preposterous. I used to make a living fixing up other people's problems as a consultant, and after doing that work for many years, you learn what is really important. Single letter parameter names, with no comments, are absolutely deadly to comprehension, and i consider them to be intentional obfuscation.

My personal opinion is that if lots of comments are needed, then the code must be hard to understand, which means they're is something wrong with the code (e.g. poorly factored). Adding comments will not fix that, and just adds noise. If the code IS understandable, then the comments are not needed either. There definitely are cases where the occasional brief comment is helpful (not all intents are clear in all cases). And there are some cases where larger comments are needed. But that is not most cases. It is definitely important to communicate intent though, and the method for doing so depends on the context. But personally, I think that code and source control history (commit messages) should be the primary sources.

Some code is just complex and should be commented, sometimes with links to references. I think it makes sense for math heavy code that might need diagrams or dense optimized code (especially assembly language or SIMD intrinsics) that needs explanation and perhaps a higher level side by side implementation. I'm also distinguishing notes (one or two lines that say why you did something) versus... what I think some of you are advocating... a more literate coding style or embedded documentation

Good points from all sides :)

In my company one of the ways to be fired for sure is to refuse to document your work so it can be transferred to others. Our guiding principle is that every key system has at least 3 people that know it, so that if someone is on vacation or getting married or sick we have coverage. Achieving 24/7 uptime only happens with multiple people "in the know". Having to repair and improve other people's code, and also working in team environments on large commercial products builds a certain discipline. Just picking good names for functions and variables is a big part of making code easier to understand for others. It is actually one of the tests that i am doing which is to take a program, give it to someone other than the author, and have them make some specific improvement or fix. You can measure this, and see how many hours it takes to accomplish the task for the new person and how much damage if any was created by the changes. The priesthood of programming has been kept in place through intentional obscurity, and companies greatly fear losing authors because often bad breakage occurs on transfer to a new person. Case in point: Apple broke printing in OSX 10.13.0, and didn't have it repaired until 10.13.4, and then broke it again in 10.14.0, and got it fixed in 10.14.2. Printing is a rather fundamental activity in a desktop computer, and you know it was all due to different people doing changes. Avoiding deep interconnections is the key factor in achieving interchangeable parts; gotta keep the linkages shallow and easy to perceive. Nothing more non-interchangeable than a 50 level deep call chain which is so common in Java programs. I consider Java one of the worst languages ever designed because of this extreme depth, and the use of OOP which creates islands of state which are un-knowable from examining the code.

Example of bad naming: https://images.app.goo.gl/EviACDgva3xHbgm28

Bad or great? It makes everything sound a lot more important and enterprise ready. I think that house is probably valued at 10x a consumer grade house is. Clearly the enterprise architect house is better.