samples: Add wire tutorial by enocom · Pull Request #357 · google/go-cloud

enocom · 2018-08-22T22:59:47Z

No description provided.

zombiezen

Nice, I really like this sample! It rounds out the last remaining principles that Go Cloud is introducing.

zombiezen · 2018-08-23T15:48:25Z

samples/wire/README.md

+values][values], as well as support for [cleanup functions][cleanup]. See the
+[Advanced Features][advanced] section for more.
+
+[readme]: https://github.com/google/go-cloud/blob/master/wire/README.md


Please alphabetize link targets.

zombiezen · 2018-08-23T15:50:34Z

samples/wire/README.md

+finally we create an event with that greeter. With all the initialization done,
+we're ready to start our event.
+
+In the design here, we are using dependency injection. We pass in whatever each


Link to https://en.wikipedia.org/wiki/Dependency_injection or a blog post? The Wikipedia article is denser than I'd like, but it's a start.

There's a good discussion on StackOverflow here that's much easier to parse than that of Wikipedia. WDYT?

Good find. That's a much more approachable explanation.

zombiezen · 2018-08-23T15:52:09Z

samples/wire/README.md

+The `Start` method holds the core of our small application: it tells the
+greeter to issue a greeting and then prints that message to the screen.
+
+Now that we have all the components of our application ready, let's wire them


Either here or earlier, the prose needs to call out that we're stepping through how a problem would be solved by a Go programmer without Wire.

zombiezen · 2018-08-23T15:54:06Z

samples/wire/README.md

+three components, so writing the initializer by hand isn't too painful. Imagine
+how useful Wire is for components that are much more complex.
+
+To show a small part of how Wire handles more complex setups, let's refactor


Nice! I really like how just adding the error bit shows that the Wire setup stays the same (more or less) and it just grows to adjust.

(And same as above: this seems like the right place to start a new section heading.)

+1 to both. I like "Grumpy."

zombiezen · 2018-08-23T15:55:50Z

samples/wire/README.md

+code and makes it easy to swap out one dependency with another. The idea of
+dependency injection isn't much more complicated than this.
+
+One downside to dependency injection is the need for so many initialization


This seems like the right place to start a new section heading.

zombiezen · 2018-08-23T15:57:22Z

samples/wire/README.md

+}
+```
+
+Let's summarize what we have done here. First, we wrote a number of components


And one last section heading: Conclusion.

zombiezen · 2018-08-23T16:00:35Z

samples/wire/main.go

+	"os"
+)
+
+func main() {


If I were coming into this without having the background knowledge of splitting application and setup code, I would be confused as to why main is in its own file. Consider moving this into greeter.go.

Moved declarations from greeter.go into main.go.

zombiezen · 2018-08-23T16:04:20Z

samples/wire/README.md

+Let's learn to use Wire by example. The [Wire README][readme] provides thorough
+documentation of the tool's usage. For readers eager to jump right in, the
+[guestbook sample][guestbook] uses Wire to initialize its components. Here we
+are going to build a small greeter CLI to understand how to use Wire. The


Consider using the term "program" here instead of "CLI". I know CLI is a fairly common acronym, but I think expanding it out helps inclusivity.

The same thought occurred to me, as well. Done.

zombiezen · 2018-08-23T16:07:29Z

samples/wire/README.md

+# Wire Tutorial
+
+Let's learn to use Wire by example. The [Wire README][readme] provides thorough
+documentation of the tool's usage. For readers eager to jump right in, the


s/jump right in/see Wire applied to a cloud server/

By being more precise, we clarify who the audience for this sample is by contrast: this is just Wire by itself.

Well said. Done.

zombiezen · 2018-08-23T16:17:09Z

samples/wire/README.md

+    }
+    return event, nil
+}
+```


One last thing that would be nice to showcase here: Wire's error messages. It doesn't have to be a long thing, but you could instruct the reader to remove one of the arguments to wire.Build (perhaps the NewGreeter call) and show that Wire points out what is missing. Another nice one to show would be to add in a superfluous function and show that Wire tells you that it is unused.

For someone who is first using Wire, I don't want them to be afraid of error messages. Much like Go compiler error messages, the intent is not to criticize, but to aid the programmer into writing the next function. If they see this being done with intent in the sample (a controlled environment), then it's more likely that when they come across it in practice that they will know that Wire is helping them know what to do next.

Great point. I'll add your two suggestions.

vangent · 2018-08-23T23:31:26Z

samples/wire/README.md

+}
+```
+
+In the intializer we assign a `Message` field to `Greeter`. Now, we can use the


nit: initializer

Fixed. Thanks!

tbpg · 2018-08-24T16:52:54Z

samples/wire/README.md

+finally we create an event with that greeter. With all the initialization done,
+we're ready to start our event.
+
+In the design here, we are using dependency injection. We pass in whatever each


My gut understanding of DI is it's automatic and done by a framework. Maybe here we should say something like "manual dependency injection"? Reading the SO post, this is DI, it's just not what's normally referred to as DI.

I think your understanding matches that of many people, i.e., there is a conflation between dependency injection as a design principle and dependency injection frameworks. I'm inclined to call out that we're using the design principle and not a framework, as a qualifier.

tbpg · 2018-08-24T16:53:46Z

samples/wire/README.md

+finally we create an event with that greeter. With all the initialization done,
+we're ready to start our event.
+
+In the design here, we are using dependency injection. We pass in whatever each


s/In the design here/In this design/

?

Alternatively, "This uses manual dependency injection."

tbpg · 2018-08-24T16:54:21Z

samples/wire/README.md

+In the design here, we are using dependency injection. We pass in whatever each
+component needs. This style of design lends itself to writing easily tested
+code and makes it easy to swap out one dependency with another. The idea of
+dependency injection isn't much more complicated than this.


Not sure we need this sentence - it makes me wonder what else is there? What do I not know?

tbpg · 2018-08-24T16:56:45Z

samples/wire/README.md

+passing it into the next one, we instead have a single call to `wire.Build`
+passing in the initializers we want to use. In Wire, initializers are known as
+"providers," functions which provide a particular type. We add a zero value for
+`Event` as a return value to satisfy the compiler. This won't be included in


Reading this, I might wonder, can I put default values in the Event or does it have to be the zero value? Or is it always ignored?

Updated to call this out.

tbpg · 2018-08-24T17:02:53Z

samples/wire/README.md

+
+Note, a [build constraint][constraint] requires a blank, trailing line.
+
+In Wire parlance, `InitializeEvent` is an injector. Now that we have our


Minor style comment: I wonder if Wire terms should be italicized, or something similar.

Following the introduction of providers above, I have quoted a new term at its first appearance.

tbpg · 2018-08-24T17:07:07Z

samples/wire/README.md

+}
+```
+
+We have added a `Grumpy` struct field to `Greeter` and if the invocation time


"Grumpy field to the Greeter struct"?

tbpg · 2018-08-24T17:07:27Z

samples/wire/README.md

+```
+
+We have added a `Grumpy` struct field to `Greeter` and if the invocation time
+of the initializer is an even number of seconds since the epoch, we will create


tbpg · 2018-08-24T17:14:53Z

samples/wire/README.md

+thing inside the generated code: it checks the error and returns early if one
+is present.
+
+As another improvement, let's look at how Wire generates code based on the


New header?

tbpg · 2018-08-24T17:18:34Z

samples/wire/README.md

+As another improvement, let's look at how Wire generates code based on the
+signature of the injector. Presently, we have hard-coded the message inside
+`NewMessage`. In practice, it's much nicer to allow callers to change that
+message however they see fit. So let's change `InitializeEvent` to look like this:


Add a sentence like:

"Wire will pass initializer arguments with the same name to any other initializers."

Maybe be a better way to phrase it.

I've added a sentence clarifying this point, although as I understand Wire decides what goes where based on types rather than names.

tbpg · 2018-08-24T17:20:33Z

samples/wire/README.md

+our component initializtion. As long as we tell Wire how to provide (i.e.,
+initialize) a component, we may add that component anywhere in the dependency
+graph and Wire will handle the rest.
+


Should we mention when the generation should be done? Should the generated code be checked into git?

It's a good point. Done.

enocom · 2018-08-24T20:21:47Z

Updated. PTAL @zombiezen, @vangent, @tbpg.

tbpg · 2018-08-24T20:27:13Z

samples/wire/README.md

+Running `wire`, we see the following:
+
+``` shell
+// wrapping the error across lines for readability


# for a shell comment.

Thanks! Good catch.

samples: Add wire tutorial

9e244e0

googlebot added the cla: yes Google CLA has been signed! label Aug 22, 2018

enocom requested review from tbpg and zombiezen August 22, 2018 23:03

enocom added 2 commits August 22, 2018 19:48

Use grumpy greeter instead of deranged greeter

577494c

Add minor additions to closing and fix typos

2633173

zombiezen reviewed Aug 23, 2018

View reviewed changes

vangent reviewed Aug 23, 2018

View reviewed changes

tbpg requested changes Aug 24, 2018

View reviewed changes

Update with comments from light@, vangent@, and tbp@

1da1340

tbpg approved these changes Aug 24, 2018

View reviewed changes

enocom added 2 commits August 24, 2018 15:34

Correct comment syntax

58b3b39

Add missing language to code sample

4bf5760

zombiezen approved these changes Aug 24, 2018

View reviewed changes

Merge branch 'master' into wire-tutorial

c3188c5

enocom merged commit 873f02f into google:master Aug 25, 2018

enocom deleted the wire-tutorial branch August 25, 2018 14:36


		Note, a [build constraint][constraint] requires a blank, trailing line.

		In Wire parlance, `InitializeEvent` is an injector. Now that we have our

Conversation

enocom commented Aug 22, 2018

Uh oh!

zombiezen left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

enocom Aug 24, 2018 •

edited

Loading