Documenting Go Github Repo

17 April 2020

The Go language makes the documentation very accessible. The documentation serves two types of clients - developers who work on the documented code, which consume it from the code itself, and code users which consume the documentation from a web UI or from the go doc command line. In Go, the documentation is a first-class citizen of the code, and writing it properly can make code development easier and results in a magnificent pkg.go.dev (the new godoc.org) site for your package. Github, the code hosting service for many Go packages, does not support Go documentation, but does support markdown readme file in the package root directory, by rendering in the home page of the repository. This page is important since it is the first thing that developers see when they find your project, and it is usually being used to get information about the project. Both the Go doc and the readme file are important - the upside is that it is possible to design them to share common content - the flipside is that constantly maintaining both of them can be a burden… Or is it?

Object Ordering in Go

03 April 2020

Order between objects is done by comparing them, but comparison is also used for equality check, which can have various meanings. Go is very strict about the comparison operators, and allows to use them only in a limited number of cases. Additionally, Go explicitly chose not to permit operator overloading (probably justifiably). As a consequence, defining order between objects generally requires defining an order function. This makes Go very safe, with a tradeoff on usability and readability. In this post, we’ll discuss orderings and comparisons in general, ordering approaches in Go, and how the order library can help.

Versioning‌ ‌with‌ ‌Branching‌ ‌Strategy‌

22 November 2019

The Go team has done an amazing work with the Go modules. They gave simple, elegant and innovative solutions to any of the many hard problems in the world of code versioning and dependency management, that made our Gopher lives better and faster. Recently, the Go team has published a blog post about best practices in incrementing major versions using Go modules called “Go Modules: v2 and Beyond” 1, in which it is instructed to use a solution of copying the code into a subdirectory (see details below). I am concerned about the many disadvantages that this recommendation hides and I fear for consequences on the future of Go libraries. In this blog post I propose another strategy, which works better common development workflows and is backward compatible with non version aware Go libraries.

Inclusion; No-Go Files in a Go Program

05 August 2019

Static files, also named assets or resources, are files that do not contain code, but used by the program. In Go, they are any non .go file. They are mostly used for web content such as HTML, javascript or images served by web servers, but they can be used by any program in the form of templates, configurations, images and so forth. The main problem is that these assets are not compiled with the source code. When developing a program, it is possible to access them from the local filesystem, but then, when the software is built and deployed, these files are not in the local filesystem anymore and we need to provide the program a way to access them. Go does not provide an out-of-the-box solution to this problem. This post will describe this problem, common solutions, and the approach taken in gitfs to handle it. A bonus section will explain some interesting aspects about the http.FileSystem interface.

Goroutine Scoped Context Proposal

10 October 2018

The context design in Go is beautiful and powerful. But like all things, it also can be improved. In this post I will present the major problems I currently see in the context system, a backward compatible solution to those problems, and a proof of concept library that implements a demo of the solution. Hopefully, you’ll be convinced that this change is necessary and can improve the user experience in the Go language.

HTTP/2 Adventure in the Go World

12 August 2018

Go’s standard library HTTP server supports HTTP/2 by default. It has great documentation, and a great demo page [code]. In this post, I will first show Go’s HTTP/2 server capabilities, and explain how to consume them as clients. Then, I will present h2conn, a library that simplifies full-duplex communication over an HTTP/2 connection.

Swagger with Go Part 2 - go-swagger

23 June 2018

In the previous post, I gave a short intro to the open API (Swagger) specification, and showed some tooling around it. In this post, I will elaborate on go-swagger, a tool that generates Go code from swagger files.

Open API with Go Part 1 - Introduction

11 June 2018

In Stratoscale, after the standard transition from a monolith to micro-services, we discovered that an “API first” approach with swagger was a good comfortable place you want to be.

A Story About Writing Scripts with Go

09 September 2017

This is a story about how I tried to use Go for scripting. In this story, I’ll discuss the need for a Go script, how we would expect it to behave and the possible implementations; During the discussion I’ll deep dive to scripts, shells, and shebangs. Finally, we’ll discuss solutions that will make Go scripts work.

Function Failure Reporting - Error or OK

01 August 2017

Go’s “multiple return values” feature, can be used for several purposes. Among them for failure reporting to the function caller. Go has two conventions for failure reporting, but currently, no clear convention for which to use when. I’ve encountered different programmers that prefer different choices in different cases. In this article, we will discuss the two, and try to make the process of choosing our next function signature more conscious.

Why I Recommend to Avoid Using the go-kit Library

11 February 2017

There is a trending ‘microservice’ library called go-kit. I’ve been using the go-kit library for a while now. The library provide a lot of convenience integrations that you might need in your service: with service discovery with Consul, distributed tracing with Zipkin, for example, and nice logic utilities such as round robin client side load balancing, and circuit breaking. It is also providing a way to implement communication layer, with support of RPC and REST.