Flip-side is less complexity and the doc comments in raw code look better. Go's generally all about, "how much can we strip away and still have things work".

Your criticisms re refactorings and links are on point though.

Trade-offs.

The problem with the Java way, as I see it, is that it puts more of a burden on the programmer to the point where a majority simply won't do it. Getting programmers to document their code is an uphill battle to begin with. But the bureaucracy that Java(doc) imposes makes it even harder to win in all but the most elite institutions. What I see a lot, is IDE-generated documentation which can be automatically inferred from the code, and is therefore redundant. While it superficially looks like documentation, it really is just line noise. I would agree that Java documentation at its best can be better than Go documentation. But I suspect that the average Go codebase is better documented than the average Java codebase.

I guess it's hard to get around to the advanced features when so few people even bother to take advantage of the basic ones.

Documentation for most Go libraries I've come across has been pathetic compared to similar things in Python or PHP.

edit: Compare to something like Racket: https://docs.racket-lang.org/plot/intro.html?q=graph#%28part...

Disagree hard on Go vs Python. Python is my day job, but documentation is rough. You're likely not going to get documentation for all the types, and if you do it's usually in one giant page and you can't tell which class's `__str__()` docstring you're looking at. Often you'll have a method with some terse description for parameters that don't completely describe the types accepted for a parameter. Most of this stuff comes for free with godoc even if you don't take the time to add a comment, and most libraries add at least some minimal comment (the linter complains if you don't). Godoc also has really nice support for executable examples, and examples run as part of the test suite so you know they're up to date.

EDIT: Racket shares many of the same problems as Python. Dynamic languages need more documentation than static languages, yet they (or rather, their users) often fail to deliver.

I'm mostly comparing this:

http://flask.pocoo.org/docs/1.0/api/#api

to this:

https://golang.org/pkg/net/http/

If the source weren't hyperlinked, I'd be lost on the latter.

edit: I love Racket's documentation. I've been using it for so many in-house things because I can just read what the function does in English--instead of having to run experiments or dig through someone else's code.

First of all, https://godoc.org/net/http is the page to visit; it serves documentation for all public packages, not just the standard library, and it's generally a little nicer. That everything is on the same site is a big deal because maintainers don't have to link to their dependencies and readers don't have to deal with the inconsistent presentation of documentation across the ecosystem.

The distinction I see is that someone put a lot more care into Flask's documentation (including the theme, which is actually a little hard to read since it renders certain things in small italic font), which is great but not indicative of the broader ecosystem. The most significant distinction wrt readability is that the Go page has types for _every_ parameter with links to the type definition. For all of the care put into the Flask doc, you still see things like this all over:

> view_func – the function to call when serving a request to the provided endpoint

I have no idea what the signature of that callback is. Meanwhile Go has https://godoc.org/net/http#HandleFunc which clearly shows the type for the handler callback (with links to types):

    func HandleFunc(pattern string, handler func(ResponseWriter, *Request))

> I love Racket's documentation. I've been using it for so many in-house things because I can just read what the function does in English--instead of having to run experiments or dig through someone else's code.

I tried to use Racket (it looks really neat), but I just spent so much time trying to figure out what to pass into each function. It was nearly impossible since types are often absent. That's just not how I want to spend my free time. :(

That sounds like a stronger defense of types than Go's documentation.

It largely is. Formalized types allow a documentation tool to do a lot of heavy lifting. But Go's documentation system is still quite a lot nicer than javadoc, doxygen, etc. for other statically typed languages.

> Godoc also has really nice support for executable examples, and examples run as part of the test suite so you know they're up to date.

Ah yes, the nice godoc feature which only got added to the python stdlib in checks note 2001.

I didn't mean to convey that it didn't exist in Python; I was just remarking that it was a nice feature. No need for the snark.

I started using Python with version 1.6, and never used for anything more than scripting tasks, so my experience is mostly related to the official docs.

The manuals provided with Python are great when compared with quite a few alternatives, some of them require to go buy a book to properly learn them.

You absolutely want to add documentation linters to your build process as early in any project as you can. Just requiring that something be in the function docstring is usually enough to get people to put at least a minimal amount of description there.

I’d argue there’s a failure of the code to some extent to need such extsenibility with documentation. I’ve often found when I need more info outside of Godocs that simply clicking through and diving into the source provided me with all the answers I needed to know.

This attitude, which I'll paraphrase as "needing any feature that I personally consider unnecessary is a code smell," is endemic to the Go community and a big reason why I still find myself frustrated by it on a daily basis even after a month of using it for a greenfield project. I don't like the language itself, since I'm generally in favor of a language offering more affordances rather than fewer, but it's fine to write in and I'm ultimately concerned with making the pragmatic choice. When I go to look for what the idiomatic way to do something is, though, wow! It's rarely just "this is the way to do it, since the language optimized for a particular use case by making the tradeoff of omitting the usual features for this": instead, it frequently goes on to assert that those features are unnecessary in nearly every case and languages that provide them are wrong, or old-fashioned, or too Academic, or the people that use them don't care about Getting Things Done. Also, throw in a few cargo-culted potshots at Java for good measure! I've used a good number of languages professionally at this point, and the Go orthodoxy is easily the most off-putting I've ever encountered. I don't know why it's become so aggressively totalizing, but it's not a good thing.

I couldn't disagree more. I think it comes down to personal preferences, mostly.

I get so much more done in Go, have fewer maintenance issues, and more frequently collaborate with other folks/contribute to other projects.

> I've used a good number of languages professionally at this point, and the Go orthodoxy is easily the most off-putting I've ever encountered.

I could -- and do -- say the same about the Java ecosystem.

For what it's worth, I don't particularly have a cross to bear with respect to Java. I cited it just because its invocations as a Bad Language bogeyman are common in the Go-focused writings I've found, and those are far out of proportion to its inherent flaws (of which I believe there are many!). I completely agree that it's a matter of preference, which I think is supported by the fact that I found Go to be the best choice of language in the context that I'm operating in whatever my reservations.

I'm confused about your assertion that the Java ecosystem has a similar problem, though, because my sense is both that it has a much less identifiable orthodoxy by virtue of being so widely used across so many domains, and that the new guard, such as it is, is very much in favor of creating libraries and utilities that favor simpler implementations and interfaces contra its "architecture astronaut" baggage.

You make a fair point; I'm not adequately exposed to the Java ecosystem, I mostly end up reading Apache projects.

I guess my remarks could be rearranged as: In general, I find Java, and the JVM friend Scala, to worship Abstraction over simplicity. Complexity is constantly confused for convenience, and that makes me sad. The number of files I need to read to understand _any_ piece of Go, I could likely count on one hand, if even. For the JVM-based approach: dozens, if not more.

Abstractions _in theory_ are great: they reduce the cognitive burden, they simplify behavior, make it easier to rationalize and cast judgement; But in practice, that just isn't true. You _always_ need to peel away the abstraction.

In Go, countless times, I've found myself reading the standard library implementation. Is this good? No, of course not. Ideally, as a consumer, I never need to look under the curtain. Things should just work. But that tends to never be true, and looking under the curtain is an important aspect of computing (c. 1970-1999) that permeates everything we do.

Go makes it really easy to look under the hood, see what's happening, and more-or-less instantly achieve clarity. The only other languages I've ever used that came close were C and C++, and history has demonstrated how well that's worked out.

To add to your point last week I cleaned up a part of project in Java sprawling in 30 or so files with 5 KLOC to 2 Java files and under 1 KLOC of Java code. Now main clean up was using library properly which was already present as dependency for years and removing innumerable level of indirections.

This code was written in really roundabout way in Java tradition where e.g. setName() would call getName() -> initName() -> initClassName() -> getDefaultClassName() -> initDefaultClassName() just to set one damn string value. And believe me this getName() function would get called grand total of one time in whole project.

And it was possible for me to do so because learning and writing Go made me confident that straightforward code is not a sign of junior/inexperienced developer. Because in Java it will be exactly that if you do not bury the actual logic in ten levels of abstract crap.

GP isn't saying that Go is not productive, but that the community has an irrationally hostile attitude towards anything that is not possible, or easy, in the language.

And I agree - it has become the prime example of "you're holding it wrong" school of programming language design and apologetics.

To the point that if someone would take the hard work to try fork and implement the features some consider missing, they would be burned on the fire instead of praised for their work, which is why anyone with the skills of doing it just goes elsewhere instead.

Do you think really Java or any other professional language would accept some language feature which was developed prior to explicit approval from committers?

If someone thinks since they have developed feature and put lot of hardwork in it so language maintainers have to merge it. I am sure they would have no option but to invent their own language.

Yes, that is how a large majority of contributions work.

Language improvement proposals aren't taken in just with words on paper.

What I found off putting is they lie about what they are doing by claiming there are 'technical' reasons[1] it has to be that way. When other languages prove that's utter BS.

I'd have more respect if they just came out and said, this style cause hey we don't want conflicts over style and since our language our way or highway. And this feature is abused a lot in other languages (we think) so we omitted it.

[1] I hate that programmers habitually lie about technical issues, especially to management and others. Because those people are as dumb as programmers think. It's why your non technical manager doesn't trust you.

Yeah, every time I need to know why my car isn't working correctly, I take it apart. All the answers I could possibly want.

Fixing a car in everyday situations is a false analogy to writing code or using library code.

The authors have chosen to make it as limited as they have on purpose, as I understand it.

I disagree with them, but here we are.

I've been slightly tempted at times to make something with markdown but never gotten enthusiastic enough to put the time. Plus, markdown is technically a bit too powerful, so I'd want to cut it back down, and before you know it I'm inflicting the 3,124th custom markdown on the world. Really I just would like bold, italic, monospace, identifier linking as you say, and numbered and bulleted lists not in the unformatted text wrapper.

I'd just like to be able to toggle javadoc, phpdoc, godoc visibility on and off entirely (not collapsed to a line, or a marker) just make them vanish until I summon them back.

I find them distracting when I'm reading the code but I don't want them not to exist either.

EDIT: Another thing I'd love to be able to do is 'tag' a variable with a synonym and have that appear next to it eveywhere.

so $strCstAcctRec (I wish that was fake but it's pretty much straight out the codebase I inherited..) would show up as $strCstAcctRec (CustomerAccountRecord).

There are a bunch of ergonomic features like that I've considered over the years, I might at some point try implementing some of them as an intellij plugin.

I've used an IDE that was aware of doxygen comments. Seems like that's close to what you want. You could right click and it'd show you the comment. I loved that IDE and it's long gone.

You should put the docs for AuthProvider on AuthProvider, not on Auth or AuthDefault.

You didn't get my point. Of course the doc should be long to where it should. In this case, I want the doc for my base function is easier to be discovered from the helper functions.

The docs for Auth() will be right next to the docs for AuthWithDefaultProvider(). Like, right above one another.

I agree. If the documentation seems duplicated, chances are the code is too. Worded oppositely, if the code is duplicated, chances are the documentation is duplicated or repetitive. Both the documentation and the main logic it describes should live in one place.