Issue 8247044: code review 8247044: doc: simplify How to write Go code article (Closed)
Descriptiondoc: simplify How to write Go code article
This version just tells you what to do, rather
than trying to teach you how it all works.
Should be much better for newcomers.
Patch Set 1 #
Total comments: 11
Patch Set 2 : diff -r b7ed25ce879b https://code.google.com/p/go #Patch Set 3 : diff -r b7ed25ce879b https://code.google.com/p/go #
Total comments: 24
Patch Set 4 : diff -r b7ed25ce879b https://code.google.com/p/go #
Total comments: 6
Patch Set 5 : diff -r 08977bd0dda2 https://code.google.com/p/go #
Total comments: 35
Patch Set 6 : diff -r 08977bd0dda2 https://code.google.com/p/go #Patch Set 7 : diff -r 08977bd0dda2 https://code.google.com/p/go #
Total comments: 1
Patch Set 8 : diff -r aa1ff597baa5 https://code.google.com/p/go #
Total comments: 22
Patch Set 9 : diff -r 1185274e7e6c https://code.google.com/p/go #Patch Set 10 : diff -r 443e4e9d1a0d https://code.google.com/p/go #MessagesTotal messages: 27
Hello golang-dev@googlegroups.com, I'd like you to review this change to https://code.google.com/p/go
Sign in to reply to this message.
Thanks Andrew, this is a big improvement. https://codereview.appspot.com/8247044/diff/1/doc/code.html File doc/code.html (right): https://codereview.appspot.com/8247044/diff/1/doc/code.html#newcode45 doc/code.html:45: accordingly. Your workspace can be located wherever you like, but we'll use Maybe add that you do not need to create src,pkg and bin as they will be created as needed. https://codereview.appspot.com/8247044/diff/1/doc/code.html#newcode60 doc/code.html:60: $ export PATH=$HOME/gocode/bin $ export PATH=$PATH:$HOME/gocode/bin https://codereview.appspot.com/8247044/diff/1/doc/code.html#newcode66 doc/code.html:66: The standard packages are given short paths such as <code>"fmt"</code> and packages from the standard library https://codereview.appspot.com/8247044/diff/1/doc/code.html#newcode126 doc/code.html:126: This command builds the <code>hello</code> package, producing an executable /s/package/command/ https://codereview.appspot.com/8247044/diff/1/doc/code.html#newcode150 doc/code.html:150: <h3>Your first library</h3> can you standardize on package or library, preferably package. https://codereview.appspot.com/8247044/diff/1/doc/code.html#newcode153 doc/code.html:153: Let's write a library and use it from the <code>hello</code> program. s/library/package
Sign in to reply to this message.
https://codereview.appspot.com/8247044/diff/1/doc/code.html File doc/code.html (right): https://codereview.appspot.com/8247044/diff/1/doc/code.html#newcode45 doc/code.html:45: accordingly. Your workspace can be located wherever you like, but we'll use On 2013/04/02 04:37:30, dfc wrote: > Maybe add that you do not need to create src,pkg and bin as they will be created > as needed. I thought about it, but I feel like each word I add to this doc reduces the number of people that will read it. https://codereview.appspot.com/8247044/diff/1/doc/code.html#newcode60 doc/code.html:60: $ export PATH=$HOME/gocode/bin On 2013/04/02 04:37:30, dfc wrote: > $ export PATH=$PATH:$HOME/gocode/bin good call. https://codereview.appspot.com/8247044/diff/1/doc/code.html#newcode66 doc/code.html:66: The standard packages are given short paths such as <code>"fmt"</code> and On 2013/04/02 04:37:30, dfc wrote: > packages from the standard library Done. https://codereview.appspot.com/8247044/diff/1/doc/code.html#newcode126 doc/code.html:126: This command builds the <code>hello</code> package, producing an executable On 2013/04/02 04:37:30, dfc wrote: > /s/package/command/ Done. https://codereview.appspot.com/8247044/diff/1/doc/code.html#newcode150 doc/code.html:150: <h3>Your first library</h3> On 2013/04/02 04:37:30, dfc wrote: > can you standardize on package or library, preferably package. Well the previous one was technically a package too, so I'm trying to draw the distinction between commands and libraries. Remember that most people reading this doc have no idea what a package is.
Sign in to reply to this message.
Should the document mention that you can $ cd $GOPATH/src/example.com/hello $ go test $ go install instead of typing the import path every time?
Sign in to reply to this message.
On 2 April 2013 17:22, <gary.burd@gmail.com> wrote: > Should the document mention that you can > > $ cd $GOPATH/src/example.com/hello > $ go test > $ go install > > instead of typing the import path every time? > Good point. I had originally written this but edited it out. I've added it again.
Sign in to reply to this message.
https://codereview.appspot.com/8247044/diff/10001/doc/code.html File doc/code.html (right): https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode28 doc/code.html:28: Go code must be be kept inside a workspace. A workspace is a directory "must be be" -> "must be" https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode75 doc/code.html:75: control repository. For instance, if your source repository is at This would be confusing for me: I'm only starting with Go, why on Earth do I need a version control repository for my first programs? A bit of clarification would help: "You don't need to publish your code to example.com before you can build it. This is just a convention adopted by Go, in practice you could have arbitrary directory names. In this case, we're using example.com as our base path..." and so on, continuing to your next paragraph. https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode122 doc/code.html:122: $ go install example.com/hello I think it would help reiterating here that "example.com/hello" is a path constructed from $GOPATH, no matter your current directory. Like "The path to the package, "example.com/hello", is always relative to our $GOPATH." And in the next paragraph you already show a simpler way -- running `go install` from inside the package's directory.
Sign in to reply to this message.
https://codereview.appspot.com/8247044/diff/10001/doc/code.html File doc/code.html (right): https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode51 doc/code.html:51: $ export GOPATH=$HOME/gocode 'gocode' is a new name in a world full of 'gothis' and 'gothat'. can we avoid a new one? what about $HOME/golang, say? or even just $HOME/go? where does the binary distribution get installed - would this conflict? https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode75 doc/code.html:75: control repository. For instance, if your source repository is at agree - you need to say that this is structured for sccs's. without that information it seems too arbitrary https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode81 doc/code.html:81: We'll use <code>example.com/</code> as our base import path. Create a use a real(er) one to make things clearer. gitub.com/xxx/yyy where xxx and yyy feel right - this whole thing should work if the reader makes one or two trivial substitutions. maybe github.com/you/hello https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode157 doc/code.html:157: </pre> Once you're happy with your program, you can commit it to your repository with a command like git -oneofthemanyconfusinggitoptions -anotherofthemanyconfusinggitoptions https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode197 doc/code.html:197: $ go install example.com/newmath you said compile but then installed. when i want to see if it compiles, i run go build. when i want to make it available, i say go install. the difference is important. you don't need to explain it all, but choose words and examples that don't muddy the waters. To see if the package compiles, run go build example.com/newmath Once it compiles, you can install it for your system with go install example.com/newmath or if you are working in the source directory, just go install https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode202 doc/code.html:202: the command above produces no output then it successfully built a package "these commands produce" drop the "above" and make it plural if you take my suggestion https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode207 doc/code.html:207: Finally, modify <code>hello.go</code> to use the <code>newmath</code> package: not finally - we're just getting started Once the newmath package is installed, modify hello.go to use it. https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode233 doc/code.html:233: </pre> worth explaining more. Whenever the go tool installs a package or binary, it also installs whatever dependencies it has. For example, if you modify the newmath package and then run just go install example.com/hello newmath will be installed as well, automatically. [i realize you're trying to keep things short but there are some details that do need to be explained or it's all just magic.] https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode244 doc/code.html:244: linux_amd64/ # this should reflect your OS and architecture s/should/will/ https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode329 doc/code.html:329: Or, running it from inside the package directory, you can omit the package path: what's "it" As always, if your shell is in the package directory, you can omit the package path in the go command:
Sign in to reply to this message.
https://codereview.appspot.com/8247044/diff/10001/doc/code.html File doc/code.html (right): https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode28 doc/code.html:28: Go code must be be kept inside a workspace. A workspace is a directory On 2013/04/02 12:02:31, alco wrote: > "must be be" -> "must be" Done. https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode51 doc/code.html:51: $ export GOPATH=$HOME/gocode On 2013/04/02 13:47:14, r wrote: > 'gocode' is a new name in a world full of 'gothis' and 'gothat'. can we avoid a > new one? what about $HOME/golang, say? or even just $HOME/go? where does the > binary distribution get installed - would this conflict? Done. https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode75 doc/code.html:75: control repository. For instance, if your source repository is at On 2013/04/02 12:02:31, alco wrote: > This would be confusing for me: I'm only starting with Go, why on Earth do I > need a version control repository for my first programs? > > A bit of clarification would help: "You don't need to publish your code to > http://example.com before you can build it. This is just a convention adopted by Go, in > practice you could have arbitrary directory names. In this case, we're using > http://example.com as our base path..." and so on, continuing to your next paragraph. Done. https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode122 doc/code.html:122: $ go install example.com/hello On 2013/04/02 12:02:31, alco wrote: > I think it would help reiterating here that "example.com/hello" is a path > constructed from $GOPATH, no matter your current directory. > > Like "The path to the package, "example.com/hello", is always relative to our > $GOPATH." And in the next paragraph you already show a simpler way -- running > `go install` from inside the package's directory. Done. https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode157 doc/code.html:157: </pre> On 2013/04/02 13:47:14, r wrote: > Once you're happy with your program, you can commit it to your repository with a > command like git -oneofthemanyconfusinggitoptions > -anotherofthemanyconfusinggitoptions > Done. https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode197 doc/code.html:197: $ go install example.com/newmath On 2013/04/02 13:47:14, r wrote: > you said compile but then installed. when i want to see if it compiles, i run go > build. when i want to make it available, i say go install. the difference is > important. you don't need to explain it all, but choose words and examples that > don't muddy the waters. > > To see if the package compiles, run > > go build example.com/newmath > > Once it compiles, you can install it for your system with > > go install example.com/newmath > > or if you are working in the source directory, just > > go install Done. https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode202 doc/code.html:202: the command above produces no output then it successfully built a package On 2013/04/02 13:47:14, r wrote: > "these commands produce" > > drop the "above" and make it plural if you take my suggestion Done. https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode207 doc/code.html:207: Finally, modify <code>hello.go</code> to use the <code>newmath</code> package: On 2013/04/02 13:47:14, r wrote: > not finally - we're just getting started > > Once the newmath package is installed, modify hello.go to use it. Done. https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode233 doc/code.html:233: </pre> On 2013/04/02 13:47:14, r wrote: > worth explaining more. > Whenever the go tool installs a package or binary, it also installs whatever > dependencies it has. For example, if you modify the newmath package and then run > just > > go install example.com/hello > > newmath will be installed as well, automatically. > > > [i realize you're trying to keep things short but there are some details that do > need to be explained or it's all just magic.] Done. https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode244 doc/code.html:244: linux_amd64/ # this should reflect your OS and architecture On 2013/04/02 13:47:14, r wrote: > s/should/will/ Done. https://codereview.appspot.com/8247044/diff/10001/doc/code.html#newcode329 doc/code.html:329: Or, running it from inside the package directory, you can omit the package path: On 2013/04/02 13:47:14, r wrote: > what's "it" > > As always, if your shell is in the package directory, you can omit the package > path in the go command: > Done.
Sign in to reply to this message.
Hello dave@cheney.net, gary.burd@gmail.com, alcosholik@gmail.com, r@golang.org (cc: golang-dev@googlegroups.com), Please take another look.
Sign in to reply to this message.
https://codereview.appspot.com/8247044/diff/18001/doc/code.html File doc/code.html (right): https://codereview.appspot.com/8247044/diff/18001/doc/code.html#newcode15 doc/code.html:15: way. Please read this document carefully. It explains the simplest way to get up and running with your Go installation. https://codereview.appspot.com/8247044/diff/18001/doc/code.html#newcode40 doc/code.html:40: workspace (or workspaces). the parentheses have thrown me off and i haven't started yet. delete the parenthetical remark https://codereview.appspot.com/8247044/diff/18001/doc/code.html#newcode76 doc/code.html:76: control repository. For instance, if your GitHub account is at what version control repository? you need a paragraph above here that explains the idea. in fact it needs to go near the 'workspace' definition. something like this. feel free to edit the go tool is designed to work with open source code maintained in public repositories. although you don't need to publish your code, the model for how the workspace is set up works the same whether you do or not. a workspace represents a collection of "repositories" of source code installed into a common library of binaries and compiled package files. the source code is maintained as a set of directories, under a common 'src' directory, one per repository. then show an example then say what GOPATH is then package paths start to make sense. i know you're trying not to explain this but what's going on is incomprehensible if you don't
Sign in to reply to this message.
https://codereview.appspot.com/8247044/diff/18001/doc/code.html File doc/code.html (right): https://codereview.appspot.com/8247044/diff/18001/doc/code.html#newcode15 doc/code.html:15: way. Please read this document carefully. On 2013/04/03 04:56:21, r wrote: > It explains the simplest way to get up and running with your Go installation. Done. https://codereview.appspot.com/8247044/diff/18001/doc/code.html#newcode40 doc/code.html:40: workspace (or workspaces). On 2013/04/03 04:56:21, r wrote: > the parentheses have thrown me off and i haven't started yet. delete the > parenthetical remark Done. https://codereview.appspot.com/8247044/diff/18001/doc/code.html#newcode76 doc/code.html:76: control repository. For instance, if your GitHub account is at On 2013/04/03 04:56:21, r wrote: > what version control repository? you need a paragraph above here that explains > the idea. in fact it needs to go near the 'workspace' definition. > > something like this. feel free to edit > > the go tool is designed to work with open source code maintained in public > repositories. although you don't need to publish your code, the model for how > the workspace is set up works the same whether you do or not. a workspace > represents a collection of "repositories" of source code installed into a common > library of binaries and compiled package files. the source code is maintained as > a set of directories, under a common 'src' directory, one per repository. > > then show an example > > then say what GOPATH is > > then package paths start to make sense. > > i know you're trying not to explain this but what's going on is incomprehensible > if you don't Done.
Sign in to reply to this message.
Hello dave@cheney.net, gary.burd@gmail.com, alcosholik@gmail.com, r@golang.org (cc: golang-dev@googlegroups.com), Please take another look.
Sign in to reply to this message.
getting close. i'll take another look tomorrow https://codereview.appspot.com/8247044/diff/26001/doc/code.html File doc/code.html (right): https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode136 doc/code.html:136: publish it someday. In practice, you can choose an arbitrary path name. this paragraph says it but it's pretty clumsy. try a rewrite. i think the solution is to reverse the order of presentation: choose a path. if your code is in a repo, that should be it. now you have the directory: $GOPATH/src/PATH https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode192 doc/code.html:192: You can also omit the package path and by running <code>go install</code> from bad grammar. rewrite. maybe you can also omit the package path if you run go install from ... https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode218 doc/code.html:218: simply type the binary name: s/simply/just/ https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode228 doc/code.html:228: repository, add the files, and commit your first change. make clear this is optional https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode262 doc/code.html:262: Next, create a file named <code>sqrt.go</code> with the following contents. in that directory https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode297 doc/code.html:297: these commands produce no output then they have executed successfully. s/then // https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode343 doc/code.html:343: Now that you have followed the steps above, your workspace should look like too many "Nows". After the steps above, your workspace... https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode427 doc/code.html:427: Now run the test with <code>go test</code>: s/Now/Then/ (ha) https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode546 doc/code.html:546: d
Sign in to reply to this message.
https://codereview.appspot.com/8247044/diff/26001/doc/code.html File doc/code.html (right): https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode136 doc/code.html:136: publish it someday. In practice, you can choose an arbitrary path name. On 2013/04/03 06:21:41, r wrote: > this paragraph says it but it's pretty clumsy. try a rewrite. i think the > solution is to reverse the order of presentation: choose a path. if your code is > in a repo, that should be it. now you have the directory: $GOPATH/src/PATH Done. https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode192 doc/code.html:192: You can also omit the package path and by running <code>go install</code> from On 2013/04/03 06:21:41, r wrote: > bad grammar. rewrite. maybe > you can also omit the package path if you run go install from ... Done. https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode218 doc/code.html:218: simply type the binary name: On 2013/04/03 06:21:41, r wrote: > s/simply/just/ Done. https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode228 doc/code.html:228: repository, add the files, and commit your first change. On 2013/04/03 06:21:41, r wrote: > make clear this is optional Done. https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode262 doc/code.html:262: Next, create a file named <code>sqrt.go</code> with the following contents. On 2013/04/03 06:21:41, r wrote: > in that directory Done. https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode297 doc/code.html:297: these commands produce no output then they have executed successfully. On 2013/04/03 06:21:41, r wrote: > s/then // Done. https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode343 doc/code.html:343: Now that you have followed the steps above, your workspace should look like On 2013/04/03 06:21:41, r wrote: > too many "Nows". > > After the steps above, your workspace... Done. https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode427 doc/code.html:427: Now run the test with <code>go test</code>: On 2013/04/03 06:21:41, r wrote: > s/Now/Then/ (ha) Done. https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode546 doc/code.html:546: On 2013/04/03 06:21:41, r wrote: > d Done.
Sign in to reply to this message.
Hello dave@cheney.net, gary.burd@gmail.com, alcosholik@gmail.com, r@golang.org (cc: golang-dev@googlegroups.com), Please take another look.
Sign in to reply to this message.
A few more corrections https://codereview.appspot.com/8247044/diff/26001/doc/code.html File doc/code.html (right): https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode32 doc/code.html:32: binaries and compiled package files. This is unclear: "of source code installed into a common library of binaries". Mixing meanings for the words "installed" and "library". Maybe, better put it along the following lines: "A workspace contains a collection of packages (represented by subdirectories) with their source code and binaries (both in specific locations inside the workspace)" https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode36 doc/code.html:36: A workspace is a directory that contains three subdirectories: The previous sentence started the same way. If you want to say "a workspace is a directory", better do it in the previous paragraph. And here you can then go on with "Each workspace contains three subdirectories:" https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode87 doc/code.html:87: (<code>oauth</code> and <code>task</code>). Not clear how is a command different from a library at this point. Add one more explanation? "The difference between commands and libraries is going to become clear soon" or "Both commands an libraries live side by side in your workspace. Go on reading to find out how they're different from each other" https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode99 doc/code.html:99: To get started, create a workspace directory and set <code>GOPATH</code> A minor thing s/create a workspace directory/create a directory for your workspace/ https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode297 doc/code.html:297: these commands produce no output then they have executed successfully. Should definitely mention that `go build` for a non-main package doesn't produce a binary. Text from "go help build", rephrased: "Running <code>go build</code> for a non-main package compiles the package but discards the results, serving only as a check that the package can be built." https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode330 doc/code.html:330: the <code>newmath</code> package will be installed as well, automatically. Not clear for a newbie. You have installed a command before (line 202), so a newbie will try to look for the package's binary in bin? Also, it kind of implies that the resulting program executable needs the newmath package installed, although in reality it's linked into the executable. It's going to be more text, but I think it's a good place at this point in the document to explain the difference between go build and go install and mention where the binaries go, to avoid surprises. https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode437 doc/code.html:437: path from the <code>go</code> tool: "If your shell is in" sounds weird. Should instead be "As always, if you are running go tool from inside the package's directory, you can omit the path:" Or maybe even use an indefinite article "a package's directory" if that's appropriate.
Sign in to reply to this message.
Thanks, this is really valuable feedback. https://codereview.appspot.com/8247044/diff/26001/doc/code.html File doc/code.html (right): https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode32 doc/code.html:32: binaries and compiled package files. On 2013/04/03 07:37:21, alco wrote: > This is unclear: "of source code installed into a common library of binaries". > Mixing meanings for the words "installed" and "library". > > Maybe, better put it along the following lines: "A workspace contains a > collection of packages (represented by subdirectories) with their source code > and binaries (both in specific locations inside the workspace)" Done. https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode36 doc/code.html:36: A workspace is a directory that contains three subdirectories: On 2013/04/03 07:37:21, alco wrote: > The previous sentence started the same way. If you want to say "a workspace is a > directory", better do it in the previous paragraph. And here you can then go on > with "Each workspace contains three subdirectories:" Done. https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode87 doc/code.html:87: (<code>oauth</code> and <code>task</code>). On 2013/04/03 07:37:21, alco wrote: > Not clear how is a command different from a library at this point. Add one more > explanation? > > "The difference between commands and libraries is going to become clear soon" or > "Both commands an libraries live side by side in your workspace. Go on reading > to find out how they're different from each other" Done. https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode99 doc/code.html:99: To get started, create a workspace directory and set <code>GOPATH</code> On 2013/04/03 07:37:21, alco wrote: > A minor thing > > s/create a workspace directory/create a directory for your workspace/ It is the workspace's directory, though. I'd like to leave this as is. https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode297 doc/code.html:297: these commands produce no output then they have executed successfully. On 2013/04/03 07:37:21, alco wrote: > Should definitely mention that `go build` for a non-main package doesn't produce > a binary. > > Text from "go help build", rephrased: > "Running <code>go build</code> for a non-main package compiles the package but > discards the results, serving only as a check that the package can be built." I would really rather avoid this. It's quite a subtle thing, and it's not going to matter in practice; if you're using a library, it'll get installed when you "go install". Otherwise, what do you expect from go build? Even if it gave you an object file, what would you do with it? https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode330 doc/code.html:330: the <code>newmath</code> package will be installed as well, automatically. On 2013/04/03 07:37:21, alco wrote: > Not clear for a newbie. You have installed a command before (line 202), so a > newbie will try to look for the package's binary in bin? Also, it kind of > implies that the resulting program executable needs the newmath package > installed, although in reality it's linked into the executable. > > It's going to be more text, but I think it's a good place at this point in the > document to explain the difference between go build and go install and mention > where the binaries go, to avoid surprises. I've added a discussion below the "your workspace should look like" https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode330 doc/code.html:330: the <code>newmath</code> package will be installed as well, automatically. On 2013/04/03 07:37:21, alco wrote: > Not clear for a newbie. You have installed a command before (line 202), so a > newbie will try to look for the package's binary in bin? Also, it kind of > implies that the resulting program executable needs the newmath package > installed, although in reality it's linked into the executable. > > It's going to be more text, but I think it's a good place at this point in the > document to explain the difference between go build and go install and mention > where the binaries go, to avoid surprises. Again, I added some discussion to the end of this section. I really don't want to break up the flow here. https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode437 doc/code.html:437: path from the <code>go</code> tool: On 2013/04/03 07:37:21, alco wrote: > "If your shell is in" sounds weird. Should instead be > > "As always, if you are running go tool from inside the package's directory, you > can omit the path:" Or maybe even use an indefinite article "a package's > directory" if that's appropriate. Done.
Sign in to reply to this message.
Hello dave@cheney.net, gary.burd@gmail.com, alcosholik@gmail.com, r@golang.org (cc: golang-dev@googlegroups.com), Please take another look.
Sign in to reply to this message.
https://codereview.appspot.com/8247044/diff/26001/doc/code.html File doc/code.html (right): https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode297 doc/code.html:297: these commands produce no output then they have executed successfully. On 2013/04/03 09:16:10, adg wrote: > On 2013/04/03 07:37:21, alco wrote: > > Should definitely mention that `go build` for a non-main package doesn't > produce > > a binary. > > > > Text from "go help build", rephrased: > > "Running <code>go build</code> for a non-main package compiles the package but > > discards the results, serving only as a check that the package can be built." > > I would really rather avoid this. It's quite a subtle thing, and it's not going > to matter in practice; if you're using a library, it'll get installed when you > "go install". Otherwise, what do you expect from go build? Even if it gave you > an object file, what would you do with it? It's just confusing the first time you build a library and see nothing produced from it. People coming from C expect to see the .a files for every source file. You've already mentioned that no output means no errors, but an additional note that says "and unlike running `go build` for a command, building a library doesn't produce any binaries, so don't worry and don't try to look for one" will help keep the reader reading instead of trying to figure out where the binary went. https://codereview.appspot.com/8247044/diff/37001/doc/code.html File doc/code.html (right): https://codereview.appspot.com/8247044/diff/37001/doc/code.html#newcode54 doc/code.html:54: more source packages. Maybe it's my English, but this whole paragraph seems unclear. I think it can be safely dropped. You've already briefly described the contents of the src dir in the list above, and you show an example of a typical workspace below.
Sign in to reply to this message.
https://codereview.appspot.com/8247044/diff/26001/doc/code.html File doc/code.html (right): https://codereview.appspot.com/8247044/diff/26001/doc/code.html#newcode297 doc/code.html:297: these commands produce no output then they have executed successfully. On 2013/04/03 09:36:35, alco wrote: > On 2013/04/03 09:16:10, adg wrote: > > On 2013/04/03 07:37:21, alco wrote: > > > Should definitely mention that `go build` for a non-main package doesn't > > produce > > > a binary. > > > > > > Text from "go help build", rephrased: > > > "Running <code>go build</code> for a non-main package compiles the package > but > > > discards the results, serving only as a check that the package can be > built." > > > > I would really rather avoid this. It's quite a subtle thing, and it's not > going > > to matter in practice; if you're using a library, it'll get installed when you > > "go install". Otherwise, what do you expect from go build? Even if it gave you > > an object file, what would you do with it? > > It's just confusing the first time you build a library and see nothing produced > from it. People coming from C expect to see the .a files for every source file. > > You've already mentioned that no output means no errors, but an additional note > that says "and unlike running `go build` for a command, building a library > doesn't produce any binaries, so don't worry and don't try to look for one" will > help keep the reader reading instead of trying to figure out where the binary > went. Done.
Sign in to reply to this message.
https://codereview.appspot.com/8247044/diff/42001/doc/code.html File doc/code.html (right): https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode47 doc/code.html:47: The <code>go</code> tool builds source packages and installs the resultant s/resultant/resulting/ use the 10-cent word https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode53 doc/code.html:53: repositories (such as Git or Mercurial) that track the development of one or s/as/as for/ https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode91 doc/code.html:91: <code>streak</code>, and <code>todo</code>) comprising two commands nice to see comprising used correctly for a change. https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode97 doc/code.html:97: Commands and libraries are both kinds of source packages. hard to parse (garden path) Commands and libraries are built from different kinds of source packages. https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode98 doc/code.html:98: We will discuss the disctinction later. s/ct/t/ put a link on "later" https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode122 doc/code.html:122: For convenience, you should add the workspace's <code>bin</code> subdirectory s/you should / https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode151 doc/code.html:151: as long as it is unique to the standard library and greater Go ecosystem. this is good now https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode218 doc/code.html:218: binary. It then installs that binary to the workspace's <code>bin</code> maybe s/to/in/ https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode219 doc/code.html:219: directory as <code>hello</code> (or, under Windows, <code>hello.exe</code>). In our example, that will be $GOROOT/bin/hello, which is $HOME/go/bin/hello. (let's be really clear about what's going on) https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode248 doc/code.html:248: repository, add the files, and commit your first change. Note that this step is s/Note that /Of course, / or /Again/ but maybe better to rewrite If you're using a source control system, once the program is working is a good time to initialize the repository, add the files, and commit the change. Again, this step is optional: you do not need to use source control to write Go code. https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode325 doc/code.html:325: modify <code>hello.go</code> to use it: maybe modify your original hello.go, which is in <directory name> (just to remind them)
Sign in to reply to this message.
PTAL https://codereview.appspot.com/8247044/diff/42001/doc/code.html File doc/code.html (right): https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode47 doc/code.html:47: The <code>go</code> tool builds source packages and installs the resultant On 2013/04/03 20:53:07, r wrote: > s/resultant/resulting/ use the 10-cent word Done. https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode53 doc/code.html:53: repositories (such as Git or Mercurial) that track the development of one or On 2013/04/03 20:53:07, r wrote: > s/as/as for/ Done. https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode91 doc/code.html:91: <code>streak</code>, and <code>todo</code>) comprising two commands On 2013/04/03 20:53:07, r wrote: > nice to see comprising used correctly for a change. Thanks. https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode97 doc/code.html:97: Commands and libraries are both kinds of source packages. On 2013/04/03 20:53:07, r wrote: > hard to parse (garden path) > Commands and libraries are built from different kinds of source packages. Done. https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode98 doc/code.html:98: We will discuss the disctinction later. On 2013/04/03 20:53:07, r wrote: > s/ct/t/ > > put a link on "later" Done. https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode122 doc/code.html:122: For convenience, you should add the workspace's <code>bin</code> subdirectory On 2013/04/03 20:53:07, r wrote: > s/you should / Done. https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode151 doc/code.html:151: as long as it is unique to the standard library and greater Go ecosystem. On 2013/04/03 20:53:07, r wrote: > this is good now Good. https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode218 doc/code.html:218: binary. It then installs that binary to the workspace's <code>bin</code> On 2013/04/03 20:53:07, r wrote: > maybe s/to/in/ I prefer "to". Maybe "Inside" ? https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode219 doc/code.html:219: directory as <code>hello</code> (or, under Windows, <code>hello.exe</code>). On 2013/04/03 20:53:07, r wrote: > In our example, that will be $GOROOT/bin/hello, which is $HOME/go/bin/hello. > > (let's be really clear about what's going on) Done. https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode248 doc/code.html:248: repository, add the files, and commit your first change. Note that this step is On 2013/04/03 20:53:07, r wrote: > s/Note that /Of course, / or /Again/ > > but maybe better to rewrite > > If you're using a source control system, once the program is working is a good > time > to initialize the repository, add the files, and commit the change. > Again, this step is optional: you do not need to use source control > to write Go code. Done. https://codereview.appspot.com/8247044/diff/42001/doc/code.html#newcode325 doc/code.html:325: modify <code>hello.go</code> to use it: On 2013/04/03 20:53:07, r wrote: > maybe > modify your original hello.go, which is in <directory name> > (just to remind them) Done.
Sign in to reply to this message.
LGTM nice work
Sign in to reply to this message.
*** Submitted as https://code.google.com/p/go/source/detail?r=b36a8b649018 *** doc: simplify How to write Go code article This version just tells you what to do, rather than trying to teach you how it all works. Should be much better for newcomers. R=dave, gary.burd, alcosholik, r CC=golang-dev https://codereview.appspot.com/8247044
Sign in to reply to this message.
On 4 April 2013 08:12, <r@golang.org> wrote: > LGTM nice work > Thanks for the comments Rob, Alexei, Dave, and Gary. I think the doc is much better now.
Sign in to reply to this message.
Message was sent while issue was closed.
On 2013/04/03 21:20:22, adg wrote: > On 4 April 2013 08:12, <mailto:r@golang.org> wrote: > > > LGTM nice work > > > > Thanks for the comments Rob, Alexei, Dave, and Gary. I think the doc is > much better now. Great job!
Sign in to reply to this message.
|
