GoogleCloudPlatform / samples-style-guide

Guidelines on writing effective Google Cloud samples.
https://googlecloudplatform.github.io/samples-style-guide/
Apache License 2.0
11 stars 19 forks source link

feat: add Go samples #43

Closed enocom closed 2 years ago

enocom commented 2 years ago

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.

enocom commented 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?

enocom commented 2 years ago

@grayside @kurtisvg @codyoss This is ready for another review. I think we have a reasonable solution for Go here.

enocom commented 2 years ago

There are a few open issues with this PR:

  1. 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.

  1. 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.

  1. 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:

  1. Moving the client initialization to a more central place where it could be shared
  2. Handling errors as needed, changing function signatures (getting rid of the io.Writer is obviously a necessity)
  3. Breaking the snippet into separate calls (assuming the developer wants to do a few things with the client).

In other words, returning or not returning the error is tangential in how the sample would be used.

enocom commented 2 years ago

@codyoss @tritone This is ready for another pass.

enocom commented 2 years ago

My PR doesn't have permission to push to the preview site.