Repository metrics
- Stars
- (133,883 stars)
- PR merge metrics
- (No merged PRs in 30d)
Description
Over the last few years, Go standard library has done a great job by improving the examples coverage. However, some of the examples are difficult to read or too comprehensive to be a reference for basic usage.
Standard library examples can help more if they were simpler and more copy/paste-able. More comprehensive scenarios can be covered as secondary examples or in other mediums such as https://gobyexample.com/.
Here are some examples:
- https://golang.org/pkg/path/filepath/#Walk It creates a directory, adds a lot of logic, prints out unix-specific comments, etc. Instead, it can demonstrate how to walk in a well known path, such as the home directory.
- https://golang.org/pkg/io/#example_TeeReader It doesn't really demonstrate a case where a TeeReader is useful. Running is required to understand what it does.
- https://golang.org/pkg/os/exec/#example_Cmd_StderrPipe It is hard to follow what the sh is supposed to do with "echo stdout; echo 1>&2 stderr". It would be more valuable if the command is something everyone can relate.
Sorry for having to nitpick these examples, there are more cases in the standard library and it would be great to turn some of these examples into more digest ones.
Having said that, I see some packages (such as the io ones) might be better with comprehensive examples where edge cases are explained and demonstrable by running the example program because APIs are not always doing a great job explaining the behavior.