DEV Community


Posted on

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

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

Top comments (8)

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.

So you can put stuff like this in your code

func ExampleReverse() {
    // Output: olleh

And they will automatically appear in the documentation.


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.

adhocore profile image

that is pretty awesome :)

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.

avalander profile image

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.

adhocore profile image

that is definitely nice thing to do πŸ‘

dayvonjersen profile image

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

tux0r profile image

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

burdettelamar profile image
Burdette Lamar

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