DEV Community

loading...

Do you put examples/ directory with sample code for integrating your library?

adhocore profile image Jitendra Adhikari ・1 min read

For me I do it sometimes, mainly when usage is complex and not everything belongs to readme.

Discussion (8)

pic
Editor guide
Collapse
quii profile image
Chris James

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.

Collapse
adhocore profile image
Jitendra Adhikari Author

that is pretty awesome :)

Collapse
david_j_eddy profile image
David J Eddy

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.

Collapse
avalander profile image
Avalander

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.

Collapse
adhocore profile image
Jitendra Adhikari Author

that is definitely nice thing to do 👏

Collapse
dayvonjersen profile image
dayvonjersen

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

Collapse
tux0r profile image
tux0r

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

Collapse
burdettelamar profile image
Burdette Lamar

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