markdown guide
 

This is one of the really nice things about Go.

It has built in support for examples in the testing framework. blog.golang.org/examples

So you can put stuff like this in your code

func ExampleReverse() {
    fmt.Println(stringutil.Reverse("hello"))
    // Output: olleh
}

And they will automatically appear in the documentation.

Example

The advantage of this over textual documentation (which often diverges from reality) is it is checked to be syntactically correct by the compiler and checked that it actually does what it says it does by running it as a test.

 
 

Golang is a pretty awesome language TBH. The more I use it, the more I like it. So much of it just makes sense. You can defiantly see the lessons the language authors learned from the past and applied forward.

 

I tend to make reference implementations in addition to or instead of sample code and examples for libraries. I made a command-line tool for linguist and a command line tool and standalone web application using vibrant and included them in the same repo as the library code.

It's nice to provide a high-level overview of an API and its functionality so users can see right away if it does something useful for them (hopefully what they've been looking for) and having something like godoc to document the API is invaluable, but I personally like to look at a full, working implementation in order to learn how to use a library and not have to fill in the blanks from minimal toy examples.

Dogfooding also helps with development and the only reason I ever make a library is because I want to use it anyway. I suppose if you're making a general-purpose library (that does string formatting or logging or vector math or something) or one with a wide surface area (like opengl, vulkan) then minimal examples make more sense, but if it does one highly specialized thing I think it's nice as a user to be able to see it in action right away (as an application) before using it programmatically (as lines of code)

That's just like my opinion man
-tso

 

Yeah, I think it's a good practice, especially when the usage of a library is not trivial. I really appreciate libraries that do this, it's nice to see a full working example that you can download and run. A while ago, following that example, I published this library with an examples folder.

 
 

Yes. (Although one example in the README is usually enough.)

 

If you have examples, you should re-run the them and verify the results for each commit.

Classic DEV Post from May 13

What cool ideas have you seen for integrating new team members?

I came across this tweet from a couple days ago and it really struck a chord with...

Jitendra Adhikari profile image
Hello World!