100 Go Mistakes 10-16

Here we go through the rest of Chapter 2

 10 - Not being aware of the possible problems with type embedding

Go allows you to not only include types as fields in structs, but also to embed them.

Essentially this makes the fields of the embedded/base type part of the "containers" interface.

Harsanyi points out that this can lead to exposing more than you might want to, since all of the base type's fields and behaviors are exposed as part of the container.

If there is reason to hide the base struct's details, rather simply include it as an unexported field and write accessors.

11 - Not using the functional options pattern


I'll admit that I hadn't heard about, or consciously noticed, this pattern before now, but it's quite brilliant.
An issue with positional arguments in complex functions is that having tons of arguments that are either null, or unused along certain paths, etc. is a real PITA.
My own preference, when factoring out the functionality into multiple functions is actually to pass through an options structure (like, in JS, maybe just some structured object with conventional fields).

This is doable in golang, but there are a few gotchas around things like differentiating between something being unused and it just having its default value (with ints, 0 versus "I didn't set it").

The functional options pattern is a quite brilliant approach that mixes anonymous functions and veriadic arguments to pretty much nail the issues we have with config.

This blog post by Soham Kamani gives a good overview.


12 - Project misorganization


Gives a quick overview of project structure and package organization in golang projects.


With regards to package organization
  • Golang has no notion of subpackages, so parent/child package relationships are more organizational than functional (there is no privileged access to internals of package X from package X/Y)
  • Avoid premature packaging, we might cause overcomplication.
  • Granularity is important to consider, we don't want hundreds of small packages (although an exception is made for those with highly cohesive functionality)
  • Name with care - we should name packages after what they provide rather than what they contain.
  • Export as little as possible. We can always export more later if necessary - this potentially reduces coupling.

13 - Creating utility packages

This is really just an argument against badly named, arbitrary "util" type packages. 

14 - Ignoring package name collisions


It's possible to introduce variable collisions and overriding for both package names and built-in functions. We should either rename our variables or (in the case of packages) alias the package name.

15 - Missing code documentation


All exported elements should be documented.

With structs, vars, functions, the convention is to "add comments, starting with the name of the exported element".
These comments should focus on what the function or variable does, not how it does it (the latter is irrelevant from the client's perspective - since it is implementation details).

Packages are also to be commented - convention is "// package NAME" followed by comments.
This could appear anywhere in the package, but if you have many files, you could add a "docs.go" file to the package.

16 - Not using linters


Use a linter. 

Comments

Post a Comment

Popular posts from this blog

JCE's Gifted and Talented Center

Image
Back in South Africa, in the early 90s, I was invited to take part in programmes offered at the Johannesburg College of Education's "Gifted and Talented Center". I can barely remember much about it. I recall that I did courses in electronics, drama, programming, and study techniques. Further, I remember the buildings and the general feeling of the place (massive buildings, alcoves with chairs and windows in the long passages between primary blocks, etc.). However, I couldn't remember very much around the nature of the programme (if, indeed, I ever knew anything about it) - who funded it, how were pupils identified, etc. I tried searching online but to no avail, there was one hit on someone's personal blog, but that was it. I did, however, manage to find the director of the JCE Gifted Child Enrichment Center from the time I attended and took a chance, asking him if he'd be willing to provide me with some information. He response was both generous and massively
Read more

100 Go Mistakes: 1-9

So I'm pretty much looking for a place to write up notes on things I'm reading - which, right now, includes Teiva Harsanyi's "100 Go Mistakes and How to Avoid Them" (does anyone else get confused when writing title-case? Let me look up the rules quick ).   Anyway, I'm at a point where I want to write down some of what I'm learning so I can refer back to it later, so let's go. 1 - Unintended variable shadowing Go's short variable declaration operator (:=) can introduce unintended effects if you're making use of it within nested blocks. Here's a simple example . The workaround is really to explicitly assign the value to the variable declared in the outer scope, either by using temporary variables when using the declaration operator, or simply assigning directly. 2 - Unnecessary nested code This provides a fairly useful heuristic with regards to code complexity. Essentially, Harsanyi wants us to try, as far as possible, to keep the "happ
Read more