README.md: update xgo style section #544
Conversation
README.md
Outdated
| ### Benchmarks | ||
|
|
||
| In most test files there will also be benchmark tests, for example in the | ||
| [clock exercise](https://github.com/exercism/xgo/blob/master/exercises/clock/clock_test.go#L75-L91). |
There was a problem hiding this comment.
Maybe we should add a Benchmark test to hello-world?
There was a problem hiding this comment.
I think so, sort of along the lines of #515 how Hello World is the first exercise that explains how things work with Go and Exercism.
robphoenix
force-pushed
the
update/readme
branch
from
59f056d to
1050696
Compare
README.md
Outdated
|
|
||
| We like errors in Go. It's not idiomatic Go to ignore invalid data or have undefined behavior. Sometimes our | ||
| Go tests require an error return where other language tracks don't. | ||
| Let's walk through the first exercise, *hello-world*. Navigate into the *hello-world* |
There was a problem hiding this comment.
Good use of navigate rather than Cd as a verb, which looked a bit weird.
README.md
Outdated
|
|
||
| ### Tests | ||
|
|
||
| *hello_test.go* uses a data-driven test. Test cases are defined as data, then a |
There was a problem hiding this comment.
It's very hard to say whether this is true of hello_test.go since it only tests a single case (since the function always returns `Hello, World!". It's true that most exercises use this though. Perhaps we can explain about the other exercises perhaps?
README.md
Outdated
|
|
||
| In Go we generally have all tests enabled and do not ask the solver to edit the | ||
| test program, to enable progressive tests for example. `t.Fatalf`, as seen | ||
| in [*hello_test.go*](https://github.com/exercism/xgo/blob/master/exercises/hello-world/hello_test.go#L26), |
There was a problem hiding this comment.
careful - this line number may get out of date.
|
I like what's going on here, with the splitting into sections. |
README.md
Outdated
| just bench the combined time to run over all the test data rather than attempt | ||
| precise timings on single function calls. They are useful if they let the solver | ||
| try a change and see a performance effect. It is important, though, to keep in | ||
| mind that benchmark tests are reflective of the machine they are run on. Benchmark |
There was a problem hiding this comment.
the section about being specific to the machine was well-placed in #545 since it is delivered with exercism fetch.
Do you see it serving a useful purpose here? I see this README file as helping out contributors to this track, and I feel a little uncertain how this will change their actions.
There was a problem hiding this comment.
No, you're right. I wanted to include something somewhere, and started in the README, but then realised it would be beneficial in the track_hints file, and just left it here. The information is more for users than someone adding an exercise/test.
robphoenix
force-pushed
the
update/readme
branch
from
1050696 to
6bf5880
Compare
|
I've rewritten parts of this after @petertseng's review comments. I decided to go back to using |
robphoenix
force-pushed
the
update/readme
branch
from
6bf5880 to
56670f8
Compare
README.md
Outdated
| ### Stub files | ||
|
|
||
| Stub files, such as `leap.go`, are a starting point for solutions. Not all exercises | ||
| need do this; this is most helpful in the early exercises for newcomers to Go. |
There was a problem hiding this comment.
need this or need to do.
There was a problem hiding this comment.
good catch, thanks.
README.md
Outdated
| directory and run `go run exercises/<problem>/example_gen.go`. | ||
|
|
||
| You should see that the `<problem>/test_cases.go` file has changed. Commit the change. | ||
| You should see that the `<problem>/test_cases.go` file has changed. Commit the |
There was a problem hiding this comment.
Change in this line might not be needed.
robphoenix
force-pushed
the
update/readme
branch
from
56670f8 to
051d568
Compare
robphoenix
force-pushed
the
update/readme
branch
from
051d568 to
7d06d40
Compare
After reading exercism/discussions#121 I
though it might be beneficial to add something to the README regarding
benchmarking on different machines. This led, as these things do, to a
small, opinionated rewrite of the xgo style section.