Closed enocom closed 2 years ago
Updated this PR to address comments.
The biggest problem here is that the guide seems to be written for languages with exceptions, and doesn't account for Go wanting to return errors. Perhaps just writing an error message to stdout is adequate?
@grayside @kurtisvg @codyoss This is ready for another review. I think we have a reasonable solution for Go here.
There are a few open issues with this PR:
- How these standards will affect the large number of existing samples. Do we migrate to this standard? Who does that work?
This is worth discussing, but is out of scope for this PR. I think we need to agree to a standard here for new samples and then decide how to handle what's already out there. I assume other languages have the same problem.
With the exception of error handling, the changes here are not a significant departure from existing Go samples.
- Are the samples meant to be production-quality?
I don't see any mention in the existing CONTRIBUTING, but have heard people say that the existing samples are meant to be production quality. This sample guide here takes a different approach and instead focuses on making the samples instructional.
- Do we return an error in sample functions, write to the io.Writer, or both?
Here are the two competing options:
// with an error return
func exampleSnippet(w io.Writer) error {
// ...
if err != nil {
return err
}
// ...
}
Versus:
// with writing the error to the io.Writer
func exampleSnippet(w io.Writer) {
// ...
if err != nil {
// TODO(developer): return or handle error as necessary
fmt.Fprintf(w, "uh-oh: %v", err)
return
}
// ...
}
In my understanding, the workflow we're designing for is copy, paste into a main func, and then run it to see what happens. In this world, the error return isn't as important as seeing how the pieces fit together. I assume adapting a snippet to production code would involve:
In other words, returning or not returning the error is tangential in how the sample would be used.
@codyoss @tritone This is ready for another pass.
My PR doesn't have permission to push to the preview site.
cc @codyoss. Here's a first pass adding support for Go. I've tried to follow the Go contributing guidelines here, but there will still be more work to bring the two guides together.