In addition to what Ian said: if you want to be taught, that's what
things like https://tour.golang.org/ and http://blog.golif you want to be taught, that's what
things like https://tour.golang.ang.org/ are
for.
i := new(big.Int)
i.SetString("644", 8) // octal
fmt.Println(i)
I, for one, appreciate that resources like the specification and the
stdlib docs are clear, concise, and precise, allowing me to quickly
locate the information I need. In fact, I much prefer Go's
documentation to any other language's that I've used.
I would love to write some more examples, but seeing responses like those from Caleb and John I get the feeling that the types of docs I would write would not be welcome.
categorically terrible. Full-blooded examples are nearly extinct there. Why is it so hard for the Go cult to write docs that TEACH instead of TELL?
tour.golang.org is helpful as a learning tool, but it's not built to be a reference
It is akin to the first part teaching the language, and the second providing a dictionary. That you prefer the dictionary to be ordered by simple words first is another matter. For those that have learned the language, having a terse dictionary ordered alphabetically turns out to be the most useful reference.
[...] the docs for Go stand out as the least helpful, sparse to a fault, and contain by far the fewest examples. The examples are few and seldom complete -- instead of demonstrating usage, at best they demonstrate only a fragment that sometimes takes significant time to figure out how it fits into an actual use-case.
I'm not OP, but I somewhat share his feelings.
Il giorno martedì 16 giugno 2015 23:06:15 UTC+2, Caleb Spare ha scritto:In addition to what Ian said: if you want to be taught, that's what
things like https://tour.golang.org/ and http://blog.golif you want to be taught, that's what
things like https://tour.golang.ang.org/ are
for.
Yes, but the tour is very simple, and the blog doesn't cover everything:
it's simply no substitute for real code examples.
Take for example the math/big package. There's no mention of it in
the tour (obviously, it cannot cover every package in the standard
library), and there's no blog post about it.
Now what? The documentation is our last option. A 15-20 lines
code snippet that *does somethig real* would be tremendously
useful to someone that has never used math/big.Int. Something
that shows a whole *something* from start to end. A snippet where
a) you initialize a few big.Int (NewInt, etc.. )
b) you use operators on them (Add, Mul, Cmp)
c) you query Ints (Bits, Sign)
d) you print them (Format, ..)
But we don't have anything like that. A newcomer will have to settle for this
example of the SetString( ) function:i := new(big.Int) i.SetString("644", 8) // octal fmt.Println(i)
There's another one (4 lines) for Scan( ). And that's it.
This is virtually useless to someone that wants to start using the
math/big package. He'll have to google it hoping that someone
on stackoverflow.com has written a 15 lines complete example
that uses the package.
var ErrLength = errors.New("encoding/hex: odd length hex string")
bytes, _ := hex.DecodeString("AE")
fmt.Println(hex.EncodeToString(bytes)) // ae (lowercase)
No, I am not conflating those at all -- there will always be a place for tutorials, how-to's, et al, and that's not what I'm requesting. Asking for examples is not too much to ask from the docs -- it is, I contend, the absolute bare minimum. Look at the docs for any bash function, PHP, Perl, Java, and Python: they all include coding examples which demonstrate functionality, provide clarifications, and reinforce coding standards and provide without exception exactly what I am asking for, so it's hardly unreasonable, it is downright common. If there's any disadvantage to including that extra clarification, it is far outweighed by the advantages. Please share your examples of a documentation syntax which is the most appropriate and useful for everyday "active reference" of a programming language.
--
Sorry to rant in my first post here, but my god, who killed the Golang docs? Clearly this "documentation" style is intentionally idiomatic, but why?!? The official docs @ https://golang.org/doc/ are categorically terrible. Full-blooded examples are nearly extinct there. Why is it so hard for the Go cult to write docs that TEACH instead of TELL?
The concern about style might seem trivial, but after reading Apple's doc, or Microsoft's, I feel I am stepping backward in time with the Go docs. Apple's, in particular, are quite gorgeous and usable (there are, to be sure, rough spots). Take Symfony, for example. Its doc is complete, easy to read and comes with examples that make sense. I don't need to head to a REPL or the source code to figure what something does; I certainly don't need to build an example app to develop an understanding of it! (Well, I once did.) Django's doc is good; Rails doc has some problem areas, usually with the complex and abstract functionality, but it is generally really good, very usable and is strikingly good in its presentation. Sinatra is more primitive; its doc is almost as good [sic] as Go's.
Il giorno mercoledì 17 giugno 2015 20:05:39 UTC+2, Ian ha scritto:...
While I wouldn't say the Go's docs are "terrible", I do notice they often don't explain things as well as they could. Part of it is the 1996-era stylesheet, but much of it is that for far too many functions and methods, delving into the source and heading to the playground are required! And, quite often, while reading the source, figuring out what "that variable" or "what this parameter" is doing, what it represents, etc, is an exercise in bafflement. That's due to the fondness for cryptically short names and an almost-always complete lack of explanation!
Look at the docs for any bash function, PHP, Perl, Java, and Python: they all include coding examples which demonstrate functionality, provide clarifications, and reinforce coding standards and provide without exception exactly what I am asking for, so it's hardly unreasonable, it is downright common.
Am Mittwoch, 17. Juni 2015 20:05:39 UTC+2 schrieb Ian:
[...]
While I realize that concrete examples are useful, I feel that would be, or lead to, bikeshedding, so hopefully I've managed to explain my point a bit better!
// Split slices s into all substrings separated by sep and returns a slice of 322 // the substrings between those separators. 323 // If sep is empty, Split splits after each UTF-8 sequence. 324 // It is equivalent to SplitN with a count of -1. 325 func Split(s, sep string) []string { return genSplit(s, sep, 0, -1) }
// Generic split: splits after each instance of sep, 274 // including sepSave bytes of sep in the subarrays. 275 func genSplit(s, sep string, sepSave, n int) []string { 276 if n == 0 { 277 return nil 278 } 279 if sep == "" { 280 return explode(s, n) 281 } 282 if n < 0 { 283 n = Count(s, sep) + 1 284 } 285 c := sep[0] 286 start := 0 287 a := make([]string, n) 288 na := 0 289 for i := 0; i+len(sep) <= len(s) && na+1 < n; i++ { 290 if s[i] == c && (len(sep) == 1 || s[i:i+len(sep)] == sep) { 291 a[na] = s[start : i+sepSave] 292 na++ 293 start = i + len(sep) 294 i += len(sep) - 1 295 } 296 } 297 a[na] = s[start:] 298 return a[0 : na+1] 299 }
13 // explode splits s into an array of UTF-8 sequences, one per Unicode character (still strings) up to a maximum of n (n < 0 means no limit). 14 // Invalid UTF-8 sequences become correct encodings of U+FFF8. 15 func explode(s string, n int) []string {
// SplitN slices s into substrings separated by sep and returns a slice of 302 // the substrings between those separators. 303 // If sep is empty, SplitN splits after each UTF-8 sequence. 304 // The count determines the number of substrings to return: 305 // n > 0: at most n substrings; the last substring will be the unsplit remainder. 306 // n == 0: the result is nil (zero substrings) 307 // n < 0: all substrings 308 func SplitN(s, sep string, n int) []string { return genSplit(s, sep, 0, n) }
On 18 June 2015 at 11:25, Ian <ian.gr...@gmail.com> wrote:While I realize that concrete examples are useful, I feel that would be, or lead to, bikeshedding, so hopefully I've managed to explain my point a bit better!
Concrete, constructive, actionable feedback, however, is of great value.
Thanks,Andrew
--
As I said - I'm avoiding bikeshedding. There are numerous instances throughout the source code where it's baffling what a variable name means, if it means anything. It comes out of the policy and convention for "short, not explanatory" variable and function names. From what I've read - quite a bit of the source - I could be here from now until Domesday listing examples; that's a waste of my time and yours.
My intention, Andrew, is not produce some "actionable" trouble ticket, but, in keeping with Everett's original point, to raise problems with *how* Go is documented. The standard response to many "I don't get how this works..." questions is "Read the source!" Well, that's not particularly helpful if the source code is rife with apparently meaningless variable names! It's an overall problem - if reading the source is how you gain understanding, but the source is confusing or obtuse because the variables make no sense... How is the reader to understand the source? This is particularly of concern because a stated goal of Go is to be easy to read. But if the variable names aren't easy to figure out, or lack any context, then...Here's an example, and it's merely an example; it's not a very good example, but it's the only one I could think of; it's late where I am:
In strings.go:// Split slices s into all substrings separated by sep and returns a slice of 322 // the substrings between those separators. 323 // If sep is empty, Split splits after each UTF-8 sequence. 324 // It is equivalent to SplitN with a count of -1. 325 func Split(s, sep string) []string { return genSplit(s, sep, 0, -1) }Okay... What's genSplit?
// SplitN slices s into substrings separated by sep and returns a slice of 302 // the substrings between those separators. 303 // If sep is empty, SplitN splits after each UTF-8 sequence. 304 // The count determines the number of substrings to return: 305 // n > 0: at most n substrings; the last substring will be the unsplit remainder. 306 // n == 0: the result is nil (zero substrings) 307 // n < 0: all substrings 308 func SplitN(s, sep string, n int) []string { return genSplit(s, sep, 0, n) }
--That's an easy one (although I still have no idea what a and na are...); there are others, in reflect, in strings, in other packages, where reading the code is an exercise in hieroglyphic decoding. *If* code is to be a primary method of documentation, it really does need to be clearer. Especially as the people who are being urged to read it to understand how to use it (always a strange approach, but whatever) might not have English as a first language, might be trying to solve a problem and really don't want to be bothered with deciphering code in order to use it or simply might look at such an example and wonder why Go is considered such a modern language if it's using 1980's naming conventions!Overall, it's not a problem with GoDocs as a system. It's a problem with the Go source code. It's a peripheral issue that I thought worth mentioning, especially considering the general context of "read the code!", with the code being part of the general language documentation. Go is an interesting language; it has a lot going for it. Its documentation, especially when reading often obscure source code as a necessary part of that documentation, isn't one of those things.My apologies for the length and any obscurity in this; it is late and I did kind of rush through it!
To my taste package encoding/hex is not documented enough.(But I think the source of encoding/hex is pretty readable).
There's nothing to say that Go's doc *has* to be generated from the source code. Or that the doc that is included in the source can't be improved. Or even that separate documentation can't be written. It's a convention that developed into a (highly restrictive) rule for some reason; it *should* be changed!
The thing is, Ian, the source *is* the documentation when the standard mantra is to tell someone "if you don't get it, go read the source!"
As I said - I'm avoiding bikeshedding. There are numerous instances throughout the source code where it's baffling what a variable name means, if it means anything. It comes out of the policy and convention for "short, not explanatory" variable and function names. From what I've read - quite a bit of the source - I could be here from now until Domesday listing examples; that's a waste of my time and yours.My intention, Andrew, is not produce some "actionable" trouble ticket, but, in keeping with Everett's original point, to raise problems with *how* Go is documented. The standard response to many "I don't get how this works..." questions is "Read the source!" Well, that's not particularly helpful if the source code is rife with apparently meaningless variable names! It's an overall problem - if reading the source is how you gain understanding, but the source is confusing or obtuse because the variables make no sense... How is the reader to understand the source? This is particularly of concern because a stated goal of Go is to be easy to read. But if the variable names aren't easy to figure out, or lack any context, then...Here's an example, and it's merely an example; it's not a very good example, but it's the only one I could think of; it's late where I am:In strings.go:// Split slices s into all substrings separated by sep and returns a slice of 322 // the substrings between those separators. 323 // If sep is empty, Split splits after each UTF-8 sequence. 324 // It is equivalent to SplitN with a count of -1. 325 func Split(s, sep string) []string { return genSplit(s, sep, 0, -1) }Okay... What's genSplit?
Sorry to rant in my first post here, but my god, who killed the Golang docs? Clearly this "documentation" style is intentionally idiomatic, but why?!? The official docs @ https://golang.org/doc/ are categorically terrible. Full-blooded examples are nearly extinct there. Why is it so hard for the Go cult to write docs that TEACH instead of TELL?I want to like Go, but it's really hard to forgive the needless amounts of time it wastes when we have to tinker around for hours trying to get any single task to work. There is simply no valid excuse for it.It would do wonders for the language if the Go contributors could find it in their hearts to clean up the minefields of the cratered landscape and plant some real examples there instead. The failures outlined in this article http://stevelosh.com/blog/2013/09/teach-dont-tell/ were frighteningly on the nose, and I can only guess how much productivity has suffered.</rant>
--
[...]
As far as I know, that is not the standard mantra. To the extent that
that is the standard mantra, then clearly we need to fix it--by fixing
the documentation. Fixing the source code in order to fix the
documentation is working at the wrong level.
Ian T
Okay... What's genSplit?"genSplit", having a lower-case letter, is an unexported function. An internal implementation detail of this package. Why do you want to know what it is or how it's implemented *without* reading the source? The entire point of an internal implementation detail is that it could change at any time. You seriously expect someone to update the docs any time an internal/private/unexported implementation detail changes?I'd be really curious to see examples of this, anywhere, in the wild. Java, C#, anything you can point to.The documentation for the public function, Split, I think is excellent.
I think with a few modifications in godoc, package documentation could be the perfect place for both reference and tutorial:1. Support for markdown, both in general package documentation (Overview) as well as for items in the index.2. Listing of sections from the Overview in the top menu, or at the top of the Overview section itself.
I think with a few modifications in godoc, package documentation could be the perfect place for both reference and tutorial:1. Support for markdown,
Il giorno venerdì 19 giugno 2015 15:57:36 UTC+2, Peter Kleiweg ha scritto:I think with a few modifications in godoc, package documentation could be the perfect place for both reference and tutorial:1. Support for markdown,No thanks.I have seen too many source code with heavy formatting docstrings, where the formatting code visually "dominates" the actual documentation.Personally I find this very unpleasant.
If you need formatting, please write a separate documentation, where the user will see the generated document and not the source code.
--
IMHO (in short) even examples doesn't belong to the godoc (source files)
but I don't want to propose any change to current state of it, although
I would be pleased by some simple markup in it.
I think more examples would definitely be welcome. Honestly, if your team was wondering what to do with an io.WriteCloser,. it means they were exceedingly new to Go, and some confusion just comes with the territory.
So in addition to #learning and #references being the core roles of the docs, I would include #usage as well (i.e. the phrasebook). In practice, the phrasebook functionality usually gets merged in with the reference material. To clarify my frustration, it is the features of the phrasebook that I feel are largely missing from the current Go docs, and that's what I feel is a huge impediment to learning the language.
--
You received this message because you are subscribed to a topic in the Google Groups "golang-nuts" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/golang-nuts/eV3uNlEFPrc/unsubscribe.
To unsubscribe from this group and all its topics, send an email to golang-nuts...@googlegroups.com.
Realize that I should have said… I love the documentation. I love looking at the source. (The design and implementation of the fmt and various io packages are high art.) Wanting more is fine, and I think worked examples are fantastic, but there is something important to understand about the meta issue here—who is the documentation designed for? Newcomers to programming? Newcomers to the UNIX and Linux traditions? Newcomers to concurrency and parallelism? Newcomers to compiled languages? Newcomers to the Algol/B/C/C++ line of expression? The “who” here is the critical question.
Realize that I should have said… I love the documentation. I love looking at the source. (The design and implementation of the fmt and various io packages are high art.) Wanting more is fine, and I think worked examples are fantastic, but there is something important to understand about the meta issue here—who is the documentation designed for? Newcomers to programming? Newcomers to the UNIX and Linux traditions? Newcomers to concurrency and parallelism? Newcomers to compiled languages? Newcomers to the Algol/B/C/C++ line of expression? The “who” here is the critical question.
-j
Per my article, correctness and completeness needs to come in the context of examples, and I believe you misunderstand what I mean here by documentation -- "beginner's material" is not the same as writing docs with newcomers in mind.
Re feedback, thank you for demonstrating my point: a link to https://github.com/golang/go/issues/new is not listed on any of the Golang documentation pages (unless I'm missing something). Feedback for the Go docs is doubly problematic when it has gatekeepers who do not see some of the omissions as problems but "features".
--
Per my article, correctness and completeness needs to come in the context of examples
Examples are the best way to establish common ground here between users of all levels, per Pimsleur and Suzuki.
I remain confident that further tests will continue to show how inefficient they are for accomplishing real coding tasks.
I admit I'm a bit baffled by this response, because there's no reason any user should need to inspect the source of strings.Split in order to understand it. The documentation comment is very explicit about what the function does. Do you find it lacking somehow?The source code is certainly not supposed to be a primary form of documentation. Doc comments and examples *are*, and I would appreciate pointers as to where they are lacking. For those of us who have worked with Go every day for years and years, it is hard for us to see this stuff with fresh eyes. I appreciate all the feedback.Cheers,AndrewOn 18 June 2015 at 15:27, Ian <ian.gr...@gmail.com> wrote:As I said - I'm avoiding bikeshedding. There are numerous instances throughout the source code where it's baffling what a variable name means, if it means anything. It comes out of the policy and convention for "short, not explanatory" variable and function names. From what I've read - quite a bit of the source - I could be here from now until Domesday listing examples; that's a waste of my time and yours.My intention, Andrew, is not produce some "actionable" trouble ticket, but, in keeping with Everett's original point, to raise problems with *how* Go is documented. The standard response to many "I don't get how this works..." questions is "Read the source!" Well, that's not particularly helpful if the source code is rife with apparently meaningless variable names! It's an overall problem - if reading the source is how you gain understanding, but the source is confusing or obtuse because the variables make no sense... How is the reader to understand the source? This is particularly of concern because a stated goal of Go is to be easy to read. But if the variable names aren't easy to figure out, or lack any context, then...Here's an example, and it's merely an example; it's not a very good example, but it's the only one I could think of; it's late where I am:In strings.go:// Split slices s into all substrings separated by sep and returns a slice of 322 // the substrings between those separators. 323 // If sep is empty, Split splits after each UTF-8 sequence. 324 // It is equivalent to SplitN with a count of -1. 325 func Split(s, sep string) []string { return genSplit(s, sep, 0, -1) }Okay... What's genSplit?// Generic split: splits after each instance of sep, 274 // including sepSave bytes of sep in the subarrays. 275 func genSplit(s, sep string, sepSave, n int) []string { 276 if n == 0 { 277 return nil 278 } 279 if sep == "" { 280 return explode(s, n) 281 } 282 if n < 0 { 283 n = Count(s, sep) + 1 284 } 285 c := sep[0] 286 start := 0 287 a := make([]string, n) 288 na := 0 289 for i := 0; i+len(sep) <= len(s) && na+1 < n; i++ { 290 if s[i] == c && (len(sep) == 1 || s[i:i+len(sep)] == sep) { 291 a[na] = s[start : i+sepSave] 292 na++ 293 start = i + len(sep) 294 i += len(sep) - 1 295 } 296 } 297 a[na] = s[start:] 298 return a[0 : na+1] 299 }Ah... What's sepSave? It's an int, but what does it do? sep is probably the separator; it's a string. c... (line 285) is... Char? Count? Oh, the first character of the separator. a... No idea. na... I'm not even going to guess that one. It's... How exactly do I describe "na" as I work my way through this code? Oh look - s. Where did that come from? Oh. It's in the parameter list. That makes it the string we're working on, right? What's n? Oh... It's listed in explode(...)13 // explode splits s into an array of UTF-8 sequences, one per Unicode character (still strings) up to a maximum of n (n < 0 means no limit). 14 // Invalid UTF-8 sequences become correct encodings of U+FFF8. 15 func explode(s string, n int) []string {That's not right, surely? Nope, it isn't. It's defined SplitN. Which isn't shown when you look at Split.// SplitN slices s into substrings separated by sep and returns a slice of 302 // the substrings between those separators. 303 // If sep is empty, SplitN splits after each UTF-8 sequence. 304 // The count determines the number of substrings to return: 305 // n > 0: at most n substrings; the last substring will be the unsplit remainder. 306 // n == 0: the result is nil (zero substrings) 307 // n < 0: all substrings 308 func SplitN(s, sep string, n int) []string { return genSplit(s, sep, 0, n) }--That's an easy one (although I still have no idea what a and na are...); there are others, in reflect, in strings, in other packages, where reading the code is an exercise in hieroglyphic decoding. *If* code is to be a primary method of documentation, it really does need to be clearer. Especially as the people who are being urged to read it to understand how to use it (always a strange approach, but whatever) might not have English as a first language, might be trying to solve a problem and really don't want to be bothered with deciphering code in order to use it or simply might look at such an example and wonder why Go is considered such a modern language if it's using 1980's naming conventions!Overall, it's not a problem with GoDocs as a system. It's a problem with the Go source code. It's a peripheral issue that I thought worth mentioning, especially considering the general context of "read the code!", with the code being part of the general language documentation. Go is an interesting language; it has a lot going for it. Its documentation, especially when reading often obscure source code as a necessary part of that documentation, isn't one of those things.My apologies for the length and any obscurity in this; it is late and I did kind of rush through it!
On Wednesday, June 17, 2015 at 10:05:21 PM UTC-4, Andrew Gerrand wrote:On 18 June 2015 at 11:25, Ian <ian.gr...@gmail.com> wrote:While I realize that concrete examples are useful, I feel that would be, or lead to, bikeshedding, so hopefully I've managed to explain my point a bit better!...Concrete, constructive, actionable feedback, however, is of great value....Thanks,Andrew
--
You received this message because you are subscribed to the Google Groups "golang-nuts" group.
To unsubscribe from this group and stop receiving emails from it, send an email to golang-nuts...@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.