11 ms·
Came from Java world, I find the Go comment and godoc are really limited. We can't link between functions, types. We don't have a standard way to declare input,
by letientai299 8y ago
Came from Java world, I find the Go comment and godoc are really limited. We can't link between functions, types. We don't have a standard way to declare input, output, don't have any distinction between a normal word and a Go identifier Refactoring using tool (e.g: Goland) usually lead to unexpected text replacements.
Take following functions, for example:
// Auth check if user credential is existed in bla, bla...
// ... (many more explanation)
Auth(user User, authProvider AuthProvider) bool
// AuthDefault check user against the default **AuthProvider**
AuthDefault(user User) bool {
return Auth(user, new(DefaultAuthProvider))
}
If only the AuthProvider in the second function's godoc be a link to the first one, we don't have to repeat the explanation for the second one. Dev will be able to discover the explanation easily via their IDE. This alone will be very helpful for the maintainability of any big projects.
- TheJazi13 8y agoI’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.
- michaelcampbell 8y agoYeah, every time I need to know why my car isn't working correctly, I take it apart. All the answers I could possibly want.
- q3k 8y agoFixing a car in everyday situations is a false analogy to writing code or using library code.
- mrbrowning 8y agoThis 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.
- xyzzy_plugh 8y agoI 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.
- mrbrowning 8y agoFor 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.
- xyzzy_plugh 8y agoYou 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.
- jerf 8y agoThe 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.
- noir_lord 8y agoI'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.
- Gibbon1 8y agoI'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.
- fwip 8y agoYou should put the docs for AuthProvider on AuthProvider, not on Auth or AuthDefault.
- shhsshs 8y agoI 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.
- letientai299 8y agoYou 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.
- fwip 8y agoThe docs for Auth() will be right next to the docs for AuthWithDefaultProvider(). Like, right above one another.
- dilap 8y agoFlip-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.
- jstewartmobile 8y agoI 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._.Plotting_3.D_.Graphs%29 https://docs.racket-lang.org/plot/intro.html?q=graph#%28part...
- weberc2 8y agoDisagree 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.
- jstewartmobile 8y agoI'm mostly comparing this: http://flask.pocoo.org/docs/1.0/api/#api http://flask.pocoo.org/docs/1.0/api/#api to this: https://golang.org/pkg/net/http/ 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.
- weberc2 8y agoFirst of all, https://godoc.org/net/http 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 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. :(
- adamlett 8y agoThe 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.