Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

[Go] Updating a few guidelines and clarifying others #6903

Closed
wants to merge 4 commits into from
Closed

[Go] Updating a few guidelines and clarifying others #6903

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
3e6b6cf
Updating a few guidelines and clarifying others
Nov 9, 2023
b29b581
Wording felt a little weird.
Nov 9, 2023
318baf1
Update docs/golang/introduction.md
RickWinter Jan 22, 2024
c97a989
Changing wording to MUST, removing redundant guideline.
richardpark-msft Mar 21, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 15 additions & 4 deletions docs/golang/introduction.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,17 +74,20 @@ Azure services will be exposed to Go developers as one or more _service client_

Your API surface consists of one or more service clients that the consumer instantiates to connect to your service, plus a set of supporting types.

{% include requirement/MUST id="golang-client-naming" %} name service client types with the `Client` suffix.

{% include requirement/MUST id="golang-client-naming-onlyclient" %} name the client `Client`. The combination of the package and the type provide enough context.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some packages may have multiple clients in them and so we can't name them all Client

```go
type WidgetClient struct {
package widget

type Client struct {
// all fields MUST NOT be exported
}

// referenced as widget.Client
```

#### Service Client Constructors

{% include requirement/MUST id="golang-client-constructors" %} provide one or more constructors in the following format that return a new instance of a service client type. The "simple named" constructor MUST use an `azcore.TokenCredential`, assuming the service supports AAD authentication. If not, then the preferred credential type is used instead. Constructors MUST return the client instance by reference.
{% include requirement/MUST id="golang-client-constructors" %} provide one or more constructors in the following format that return a new instance of a service client type. The "simple named" constructor (eg: `NewClient`) MUST use an `azcore.TokenCredential`, assuming the service supports AAD authentication. If not, then this constructor should not exist. Constructors MUST return the client instance by reference.

```go
// NewWidgetClient creates a new instance of WidgetClient with the specified values.
Expand Down Expand Up @@ -443,6 +446,14 @@ TODO

{% include requirement/MUST id="golang-errors" %} return an error if a method fails to perform its intended functionality. For methods that return multiple items, the error object is always the last item in the return signature.

{% include requirement/MUST id="golang-errors-pointer" %} return custom errors (such as `azcore.ResponseError`) as a pointer. For instance:

```go
func example() error {
return &azcore.ResponseError{}
}
```

{% include requirement/SHOULD id="golang-errors-wrapping" %} wrap an error with another error if it would help in the diagnosis of the underlying failure. Expect consumers to use [error helper functions](https://blog.golang.org/go1.13-errors) like `errors.As()` and `errors.Is()`.

```go
Expand Down