Future-Proof Go Packages

2023-09-27

Abhinav Gupta

Hello!

👋 I’m Abhinav

Gopher @ Rippling

Previously: Pulumi, Uber

Agenda

What are future-proof packages
What gets in the way
Future-proofing packages
- Finding and fixing issues
- Preventing issues

What makes a package future-proof?

The ability to evolve in functionality
without disrupting the code base

Disruption

Being forced to modify code
as a result of an unrelated change

What causes disruption?

Changes to packages with
a design that leaks complexity

On complexity

Complexity is inevitable
Good design hides complexity
Complexity leaks cause fragility
Fragility causes disruption

Future-proofing packages

Planning for expansion

🧮 Functions
💡 Abstractions

🧮 Expanding functions

Parameter objects
Result objects
Functional options

Parameter objects

Put the inputs into a struct

type ClientConfig struct {
  URL string
}

func New(cfg *ClientConfig) *Client {
  return &Client{
    /* ... */
  }
}

Parameter objects

Put the inputs into a struct

Use for >3 parameters
not counting context.Context
New parameters must be optional

type ClientConfig struct {
  URL string
  Log *slog.Logger
}

func New(cfg *ClientConfig) *Client {
  log := cfg.Log
  if log == nil {
    log = DiscardLogger
  }
  return &Client{
    log: log,
    /* ... */
  }
}

Result objects

Put the outputs into a struct

type ListResult struct {
  Items      []*Item
  ContinueAt ItemID
}

func List(from *ItemID) (*ListResult, error) {
  /* ... */
}

Result objects

Put the outputs into a struct

Use for >2 returns
not counting error
Obvious field names

type ListResult struct {
  Items      []*Item
  ContinueAt ItemID
  Remaining  int
}

func List(from *ItemID) (*ListResult, error) {
  /* ... */
}

Functional options

🙂

Flexible
Customizable

🙁

Complex

type Option func(*clientOptions)

func New(opts ...Option) *Client {
  var options clientOptions
  for _, opt := range opts {
    opt(&options)
  }
  /* ... */
}

type clientOptions struct {
  logger *slog.Logger
}

func WithLogger(l *slog.Logger) Option {
  return func(o *clientOptions) {
    o.logger = l
  }
}

Functional options

type Option func(*clientOptions)

func New(opts ...Option) *Client {
  var options clientOptions
  for _, opt := range opts {
    opt(&options)
  }
  /* ... */
}

type clientOptions struct {
  logger *slog.Logger
  /* ... */
  httpClient *http.Client
}

func WithLogger(l *slog.Logger) Option {
  return func(o *clientOptions) {
    o.logger = l
  }
}

func WithHTTPClient(c *http.Client) Option {
  return func(o *clientOptions) {
    o.httpClient = c
  }
}

Functional options

🙁

High boilerplate
Harder to test
Corner cases

🙂

Several options
Few required inputs
not as options
Composability

Don’t use by default. Prefer parameter objects.

I could have a longer discussion about functional options, but for lack of time, I’ll summarize it: (step)

Functional options require a high amount of boilerplate
It’s harder for consumers to test their usage of APIs that use functional options. For example, is my mock matching against the options or their effect?
- Remember that these objects are just function references. You cannot inspect or compare them.
Options come with corner cases that people don’t often think about. What happens if I provide the logger option twice? Is that a replacement or a merge? If it’s a merge, how do I un-provide a logger that someone else provided to the options slice?

On the good side (step), functional options are probably a good fit if you intend to have many many options and very few required inputs. (step) Required inputs must not be options — the names should make that obvious.

(step) Again, functional options are a great tool when they fit, but that’s not the default. Don’t reach for them by default. Prefer parameter objects.

💡 Expanding abstractions

Accept interfaces
Return structs

Accept `interface`s

Dependencies should be interfaces
not concrete implementations

🙁

func Parse(f *os.File) (Node, error)

func Login(c *Client) error

🙂

func Parse(r io.Reader) (Node, error)

func Login(c AuthClient) error

type AuthClient interface {
  Authenticate(Credentials) error
}

Accept `interface`s

Extend by upcasting interfaces

func Parse(r io.Reader) (Node, error) {
  /* ... */
}

Accept `interface`s

Extend by upcasting interfaces

Breaks if wrapped

type countLines struct{ io.Reader }
Parse(&countLines{file}) // oops!

Make it obvious
Use small interfaces

func Parse(r io.Reader) (Node, error) {
  name := "<unknown>"
  if src, ok := r.(Source); ok {
    name = src.Name()
  }
  /* ... */
}

type Source interface {
  io.Reader
  Name() string
}

I define a new interface named Source. Its Name() method matches os.File.Name().

So if the io.Reader passed into Parse implements this method, I’ll use the file name. Otherwise, I’ll fall back to unknown.

This method is great; it allows me to optionally upgrade an abstraction I’m consuming and make it richer.

However, it’s not magic. It’s easily breakable. (step) If a user wraps the interface in an object that doesn’t know to implement the optional functionality, that upgrade path is lost.

To help mitigate that:

(step) Make the upgrade path obvious with documentation and convention. Make it so that a caller loses the upgrade path only if they intended to.
(step) And prefer to use smaller interfaces. It’s easier to talk about the upgrade path when there’s only one method to talk about.

Return `struct`s

Return concrete implementations
not interfaces

🙁

type Client interface {
  List() (ListResult, error)
}

func New() Client {
  return &impl{/* ... */}
}

type impl struct{/* ... */}

func (*impl) List() (ListResult, error)

🙂

type Client struct{ /* ... */ }

func New() *Client {
  return &Client{/* ... */}
}

func (*Client) List() (ListResult, error)

Return `struct`s

Extend by adding new methods

🙁

 type Client interface {
   List() (ListResult, error)
+  Put(PutRequest) error /* BAD */
 }

Disruptive:
Breaks other implementations
(e.g. mocks, middleware)

🙂

 func (*Client) List() (ListResult, error)
+func (*Client) Put(PutRequest) error

Planning for expansion

	📥 Input	📤 Output
🧮 Functions	Parameter Objects	Result Objects
Functional options
💡 Abstractions	Accept interfaces	Return structs

📥 Input

📤 Output

Parameter Objects

Result Objects

Functional options

Accept interfaces

Return structs

Finding and fixing problems

Built-in obsession

Reluctance to declare types, instead preferring built-in types

🧵 String overuse
🗺️ Map overuse
🎂 Boolean overuse

🧵 String overuse

Over-reliance on strings

func isHTTP(addr string) bool {
  return strings.HasPrefix(addr, "http://") ||
    strings.HasPrefix(addr, "https://")
}

func download(addr string) {
  if isHTTP(addr) {
    http.Get(addr)
  } else {
    log.Panic("unsupported:", addr)
  }
  /* ... */
}

🧵 String overuse

Over-reliance on strings

func isHTTP(addr string) bool {
  return strings.HasPrefix(addr, "http://") ||
    strings.HasPrefix(addr, "https://")
}

func isSSH(addr string) bool {
  return strings.HasPrefix(addr, "ssh://")
}

func sshDownload(addr string) {
  addr = strings.TrimPrefix(addr, "ssh://")
  /* ... */
}

func download(addr string) {
  if isHTTP(addr) {
    http.Get(addr)
  } else if isSSH(addr) {
    sshDownload(addr)
  } else {
    log.Panic("unsupported:", addr)
  }
  /* ... */
}

🧵 String overuse

Parse, don’t validate

— Alexis King

Turn string into struct
struct value is evidence of validity
Eliminate chaos early

🧵 String overuse

Over-reliance on strings

func isHTTP(addr string) bool {
  return strings.HasPrefix(addr, "http://") ||
    strings.HasPrefix(addr, "https://")
}

func isSSH(addr string) bool {
  return strings.HasPrefix(addr, "ssh://")
}

func sshDownload(addr string) {
  addr = strings.TrimPrefix(addr, "ssh://")
  /* ... */
}

func download(addr string) {
  if isHTTP(addr) {
    http.Get(addr)
  } else if isSSH(addr) {
    sshDownload(addr)
  } else {
    log.Panic("unsupported:", addr)
  }
  /* ... */
}

🧵 String overuse

Chaos to order

func isHTTP(addr *url.URL) bool {
  return addr.Scheme == "http" ||
    addr.Scheme == "https"
}

func isSSH(addr *url.URL) bool {
  return addr.Scheme == "ssh"
}

func sshDownload(addr *url.URL) {
  /* ... */
}

func download(addrs string) {
  addr, err := url.Parse(addrs)
  if err != nil {
    log.Panic(err)
  }
  if isHTTP(addr) {
    http.Get(addrs)
  } else if isSSH(addr) {
    sshDownload(addr)
  } else {
    log.Panic("unsupported:", addr)
  }
  /* ... */
}

🧵 String overuse

🙁 🙂

🙁	🙂
`strings.HasPrefix(addr, "ssh://")`	`u, err := url.Parse(addr)`
`var uuid string`	`type UUID [16]byte func ParseUUID(string) (UUID, error)`
`var ts int64`	`t := time.UnixMilli(ts)`
`strings.Replace(s, "%VAR%", val)`	`type Node struct{ Var, Str string } type Template []Node func Parse(string) Template`	`tmpl := Parse(s) tmpl.Render( map[string]string{"VAR": val}, )`

strings.HasPrefix(addr, "ssh://")

u, err := url.Parse(addr)

var uuid string

type UUID [16]byte
func ParseUUID(string) (UUID, error)

var ts int64

t := time.UnixMilli(ts)

strings.Replace(s, "%VAR%", val)

type Node struct{ Var, Str string }
type Template []Node
func Parse(string) Template

tmpl := Parse(s)
tmpl.Render(
  map[string]string{"VAR": val},
)

🗺️ Map overuse

Over-reliance on maps

Uninformative type

Business constraint in signature
Will uniqueness always be required?

func BulkRegister(users map[string]string) error {
  /* ... */
}

func Register(email, login string) error {
  /* ... */
}

Overuse of maps is another easy way to leak complexity. Let me share an example. (step)

We have a function that creates user accounts in bulk. User logins are unique, so we made it accept a map.

(step) Right off the bat, this hurts maintainability with that uninformative type signature. What’s the map key? What’s the value? Is it from login to email address, or email address to login? You can’t tell by looking at the signature.
- (step) If you have the Register function handy, you might be able to guess that it’s from email to login.
- Regardless, I’m wary of anytime I see a map cross a package boundary.
(step) Next, it leaks a mutable business constraint in the immutable type signature.
- Does the email address actually have to be unique? Will it forever be required to be unique? Many service support multiple accounts from the same email address. If we ever decide to do that, we’ll have a pretty disruptive change on our hands.

At a boundary like this, it’s best to accept a slice of structured information, and handle uniqueness requirements internally.

🗺️ Map overuse

Over-reliance on maps

Uninformative type

Business constraint in signature
Will uniqueness always be required?

func BulkRegister(reqs []RegisterRequest) error {
  emails := make(map[string]struct{})
  for _, r := range reqs {
    if _, used := emails[r.Email]; used {
      return fmt.Errorf("email already used: %v", r.Email)
    }
    emails[r.Email] = struct{}{}
  }
  /* ... */
}

type RegisterRequest struct {
  Email, Login string
}

🗺️ Map overuse

🙁 🙂

🙁	🙂
`map[string][]string`	`[]PackageCoverage`	`type PackageCoverage struct { ImportPath string CoverFiles []string }`
`map[string]map[string]int`	`[]RateLimit`	`type RateLimit struct { From, To string RPS int }`
`map[string]*HealthCheck`	`[]*HealthCheck`

map[string][]string

[]PackageCoverage

type PackageCoverage struct {
  ImportPath string
  CoverFiles []string
}

map[string]map[string]int

[]RateLimit

type RateLimit struct {
  From, To string
  RPS      int
}

map[string]*HealthCheck

[]*HealthCheck

Here are a couple examples inspired by real code.

The left side has the map type that a function was accepting or returning. The right side has the slice it was replaced with, without any loss in functionality

We have,

map of string to slice of strings: This just listed a bunch of file names grouped by an import path.
a nested string map with an integer: This was just a list of rate limit rules. I really like this example because there’s just so much information lost about the problem at hand by using a map there.
The last one was a mapping of component name to health check for that component.
- This one is interesting because the slice version is not that much different from the map version.
- The effect of this change was that we dropped the completely unnecessary uniqueness requirement on the component name. The name was used just for logging — there was no business reason for it to be unique.

Just to clarify, I’m not trying to say "maps are bad, actually." The point I’m hoping to make is:

Map overuse leaks complexity and implementation details. And it locks you into business constraints that won’t always hold.
Therefore, maps crossing package boundaries deserve extreme scrutiny. Often you’ll find that the map is an implementation detail that you can hide away.

🎂 Boolean overuse

Overly specific booleans

type SiteGen struct {
  /* ... */
}

func (g *SiteGen) RelativeURL(dst *Page) string {
  u := /* ... */
  return u + "/"
}

g.RelativeURL(p) // "path/to/dst/"

🎂 Boolean overuse

Overly specific booleans

func (...) RelativeURL(
  dst *Page,
  slash bool,
) string

Disruptive
Poorly scoped

type SiteGen struct {
  /* ... */
  AddSlash bool
}

Disruptive

type SiteGen struct {
  /* ... */
  OmitSlash bool
}

Good
Not terrible

Let’s consider some options for the opt-out.

(step) Add a slash parameter to RelativeURL.
- This will disrupt all calls to RelativeURL across the code base. That already makes it a non-starter.
- On top of that, it’s also poorly scoped:
  - Even without looking at its implementation, we can guess that SiteGen is used once per website. On the other hand, RelativeURL will be used many times per website.
  - The slash parameter will not change between these calls because whether relative URLs should use slashes is not something that changes for each URL; you decide it once when you’re generating the site. It’s site-scoped, not URL scoped.
(step) Okay, we could move it into a SiteGen level boolean.
- That’s still not good enough. It’s disruptive because the zero value — the default value — of this new optional field is to not add the slashes, which changes behavior for all existing uses of SiteGen.
(step) Fine, let’s flip it. An OmitSlash field.
- That’s good, (step) riiiight?
- (step) It’s… Not great. Not terrible.
- One of its problems is that it’s rigid and limiting. By being so specific, it limits what we can do in the future. What if we want to support adding .html as an option? Would that be another boolean? AddHTML? What happens when both booleans are set?

To figure out a better option, we have to stop thinking of this feature in isolation. The behavior has to be considered as part of the bigger SiteGen abstraction.

How about, instead of a binary choice of "add a slash or not," we think about it as "this is how links SiteGen should render links."

Perhaps "which of these N methods of rendering links should I use?" And there’s a standard tool for picking one of N…

🎂 Boolean overuse

Use an enum

type LinkStyle int

const (
  LinkStyleDir   LinkStyle = iota
  LinkStylePlain
)

type SiteGen struct {
  /* ... */
  LinkStyle LinkStyle
}

🎂 Boolean overuse

Use an enum

type LinkStyle int

const (
  LinkStyleDir   LinkStyle = iota
  LinkStylePlain
  LinkStyleHTML
)

type SiteGen struct {
  /* ... */
  LinkStyle LinkStyle
}

🗣️🔊 But wait, there’s more 📢

➿ Callback overuse

Function reference lock-in

Opaque
Inflexible

type SiteGen struct {
  /* ... */
  LinkStyle func(string) string
}

func LinkStyleDir(string)   string { ... }
func LinkStylePlain(string) string { ... }
func LinkStyleHTML(string)  string { ... }

func (g *SiteGen) RelativeURL(dst *Page) string {
  styleLink := g.LinkStyle
  if styleLink == nil {
    styleLink = LinkStyleDir /* default */
  }
  /* ... */
}

Callback overuse.

The previous section used enums to define link styles. But we could’ve gone a different direction: callbacks.

(step) Define LinkStyle as any function that takes a string and returns a string.
(step) Export three functions matching that signature. These are the default styles.
(step) Use the injected value, falling back to the default.
User can use one of the pre-defined styles, or write their own.

This isn’t terrible. It’s also not great.

(step) It’s very opaque; It’s just a function reference. We don’t know what’s inside a LinkStyle. We can’t inspect it, analyze it, or compare it.
(step) It’s inflexible: We cannot expand it. For example, if I decide that link styles need metadata about the page, I can’t do that easily.

Earlier in the talk, I mentioned that if we want to plan for expansion, we should accept interfaces instead of concrete implementations.

We can apply that here too!

➿ Callback overuse

Use an interface

type LinkStyler interface {
  StyleLink(string) string
}

type DirLinkStyler   /* ... */
type PlainLinkStyler /* ... */
type HTMLLinkStyler  /* ... */

type SiteGen struct {
  /* ... */
  LinkStyler LinkStyler
}

func (g *SiteGen) RelativeURL(dst *Page) string {
  styler := g.LinkStyle
  if styler == nil {
    styler = new(LinkStyleDir) /* default */
  }
  /* ... */
}

➿ Callback overuse

Upcast the interface

type LinkStyler interface {
  StyleLink(string) string
}

type PageLinkStyler interface {
  StylePageLink(*Page, string) string
}

type SiteGen struct {
  /* ... */
  LinkStyler LinkStyler
}

func (g *SiteGen) RelativeURL(dst *Page) string {
  styler := g.LinkStyle
  if styler == nil {
    styler = new(LinkStyleDir) /* default */
  }
  /* ... */
  if pl, ok := styler.(PageLinkStyler); ok {
    link = pl.StylePageLink(page, link)
  } else {
    link = linkStyler.StyleLink(link)
  }
  return link
}

Global state

🍝 Implicit process globals

Process globals include

os.Stdout
os.Stdin
os.Stderr
os.Getenv(k)
os.Setenv(k, v)

if os.Getenv("FEATURE_MAGIC") != "" {
  fmt.Println("You're a wizard")
  return doMagic()
}
return beBoring()

Don’t touch process globals outside main
Isolate business logic from process state

🍝 Implicit process globals

Extract and inject process globals early in main

os.Getenv("FEATURE_MAGIC")

func main() {
  feats := Features{Magic: os.Getenv("FEATURE_MAGIC")}
  run(feats)
}

fmt.Println(
  "You're a wizard",
)

func main() {
  run(os.Stdout)
}

func run(stdout io.Writer)

os.Getenv

func main() {
  run(os.Getenv)
}

func run(
  getenv func(string) string,
)

🍝 Implicit process globals

Inject process globals

type cliParams struct {
  Stdout io.Writer
  Stderr io.Writer
  Getenv func(string) string
}

func run(*cliParams)

type App struct {
  Stdout io.Writer
  Stderr io.Writer
  Getenv func(string) string
}

func (*App) Run(args []string) (exitCode int)

Interface misuse

🥚 Premature interfaces
🦖 Big interfaces

🥚 Premature interfaces

Unnecessary
Interfaces match dynamically
Inflexible
New methods are disruptive
Complex
Constructor is required

type Client interface {
  List() ([]*Post, error)
}

func New() Client {
  return &impl{/* ... */}
}

type impl struct{/* ... */}

func (*impl) List() ([]*Post, error) {
  /* ... */
}

Premature interfaces.

This is a pretty common thing. We’re defining an abstraction, so we define it as an interface, and keep the implementation private.

I want to advise against this as your default choice because

(step) It’s unnecessary. Go matches interfaces dynamically, so a type doesn’t need to declare interfaces it implements at declaration time.
(step) It introduces inflexibility. We cannot expand the interface easily. Adding new methods to this interface is a disruptive change because it’ll break other implementations.
1. And if that’s not a concern because there aren’t other implementations, then we go back to: it’s unnecessary.
(step) It comes with a minimum required complexity. You have to define a constructor; there’s no way to use the zero value or plain object directly.

Looking back to the expansion section, the fix is to…

🥚 Premature interfaces

Use a struct

Producers expose concrete types
Consumers define interfaces

type PostClient interface {
  List() ([]*Post, error)
}

func NewHandler(pc PostClient) *Handler {
  /* ... */
}

type Client struct{/* ... */}

func New() *Client {
  return &Client{/* ... */}
}

func (*Client) List() ([]*Post, error) {
  /* ... */
}

🥚 Premature interfaces

Producers may define interfaces for…

Single operation interfaces
Multiple implementations
Wrapped abstractions
Others

🦖 Big interfaces

Big interfaces cause
a tight coupling
between abstractions

The bigger the interface,
the weaker the abstraction.

Gopherfest 2015
— Rob Pike

🦖 Big interfaces

Making interfaces smaller

Follow the request path
Use functions
Build a strong core

Follow the request path

Add methods from
the request path

type Store interface {
  Get(string) (string, error)
  Set(k, v string) error
}

No Close()

s := NewRedisStore(addr)
defer s.Close()
run(s)
// Given,
//   func run(Store)

type RedisStore struct{ /* ... */ }

func NewRedisStore(addr string) *RedisStore

func (*RedisStore) Get(string) (string, error)

func (*RedisStore) Set(k, v string) error

func (*RedisStore) Close()

Follow the request path.

When deciding what goes on the interface, don’t just list all the methods of the object on the interface. Think about the request path: methods of the object that consumers will want to call — probably many times.

For example, suppose we have this key-value store backed by Redis. It has Get and Set methods as you might expect, and a Close method to close the store and clean up resources.

What should go in the interface? Follow the request path says:

(step) only Get and Set
(step) no Close

Why?

Close is not part of the request path — it won’t be called many times. It will be called exactly once (step) probably in main, when we set up the Redis store.
Plus if you think about it, not every Store will have a Close method. An in-memory data store probably won’t.

So we leave Close out of the interface.

Use functions

Convenience methods stay out of the interface

func (s *RedisStore) SetMany(ks, vs []string) error {
  for i, k := range ks {
    err := s.Set(k, vs[i])
    if err != nil {
      return nil, err
    }
  }
  return nil
}

Use functions

Convenience methods stay out of the interface

func SetMany(s Store, ks, vs []string) error {
  for i, k := range ks {
    err := s.Set(k, vs[i])
    if err != nil {
      return nil, err
    }
  }
  return nil
}

func (s *RedisStore) SetMany(
  ks, vs []string,
) error {
  return s.redisc.superFastSetMany(ks, vs)
}

Use functions

Convenience methods stay out of the interface

func SetMany(s Store, ks, vs []string) error {
  if sm, ok := s.(SetManyStore); ok {
    return sm.SetMany(ks, vs)
  }
  for i, k := range ks {
    err := s.Set(k, vs[i])
    if err != nil {
      return nil, err
    }
  }
  return nil
}

type SetManyStore interface {
  Store
  SetMany(ks, vs []string) error
}

func (s *RedisStore) SetMany(
  ks, vs []string,
) error {
  return s.redisc.superFastSetMany(ks, vs)
}

Upcast to upgrade

Build a strong core

Wrap a small interface with powerful functionality

type DataStore struct{ s Store }

func (*DataStore) Get(string) (string, error)
func (*DataStore) Set(k, v string) error

type Store interface {
  Get(string) (string, error)
  Set(k, v string) error
}

func (d *DataStore) SetMany(ks, vs []string) error {
  if sm, ok := s.(SetManyStore); ok {
    return sm.SetMany(ks, vs)
  }
  /* ... */
}

type SetManyStore interface {
  Store
  SetMany(ks, vs []string) error
}

Zooming out

🌊 Flow of information

Flow in one direction without backtracking

🌊 Flow of information

Flow in one direction without backtracking

🌊 Flow of information

Zigzagging flow indicates a leak

🔍 Scope

Application scope

Does not change between requests

Command line arguments
Environment variables

Request scope

Changes for each request

HTTP request
???

🔍 Scope

Scope is relative

Whether something is request scope or application scope depends on your point of view.

Command line arguments are application scope, yes. But from the point of view of a command line argument parser, they’re request scope.

So instead of a binary definition, think of scope as a gradient. (step)

As we go from left to right, the scope of each value gets smaller because it changes more often.
So things on the left are application scoped to those on the right, and things on the right are request scoped to those on the left.

For example, flag.Parse views this from further left of os.Args, so from its point of view, os.Args is request scope. On the other hand, http.Handler views it from further right, so from its point of view, os.Args is application scope.

Thinking about the relative scope of different values can be really helpful in writing code.

🔍 Scope

Structs	Large scope: fields Small scope: parameters
Interfaces	Request-scoped methods on the interface	`type Store interface { Get(string) (string, error) Set(k, v string) error }`
Parameters	Sort by scope (big to small)	`func GetUser( org, username string, ) *User`

Large scope: fields
Small scope: parameters

Request-scoped methods
on the interface

type Store interface {
  Get(string) (string, error)
  Set(k, v string) error
}

Sort by scope (big to small)

func GetUser(
  org, username string,
) *User

Surface area

📦 Surface area and depth

Wide and shallow packages

Frequent entry and exit
May cause zigzagging

Narrow and deep packages

Very few entry points
Upfront design work

Business packages should be narrow and deep

📦 Surface area and depth

Might be wide and shallow if
there are top-level functions that

Do RPC and IO
Access global state
Have shared arguments
Are interrelated
Are in 'util'

Finding the abstraction

🔭 Large scoped conditions

Remove special cases based on conditions
that don’t change in the current context

🔭 Large scoped conditions

type SiteGen struct {
  /* ... */
  LinkStyle LinkStyle
}

type LinkStyle int

const (
  LinkStyleDir   LinkStyle = iota
  LinkStylePlain
  LinkStyleHTML
)

func (g *SiteGen) RelativeURL(dst *Page) string {
  /* ... */
  switch g.LinkStyle {
  case LinkStyleDir:
    return u + "/"
  case LinkStylePlain:
    return strings.TrimSuffix(u, "/")
  case LinkStyleHTML:
    return u + ".html"
  }
}

🔭 Large scoped conditions

type SiteGen struct {
  /* ... */
  LinkStyler LinkStyler
}

func (g *SiteGen) RelativeURL(dst *Page) string {
  /* ... */
  return g.LinkStyler.StyleLink(u)
}

type LinkStyler interface {
  StyleLink(string) string
}

type (
  DirLinkStyler   /* ... */
  PlainLinkStyler /* ... */
  HTMLLinkStyler  /* ... */
)

func (DirLinkStyler) StyleLink(u string) string {
    return u + "/"
}

func (PlainLinkStyler) StyleLink(u string) string {
    return strings.TrimSuffix(u, "/")
}

func (HTMLLinkStyler) StyleLink(u string) string {
    return u + ".html"
}

🚧 Partial function application

Find large scoped function parameters
and wrap them into objects

🚧 Partial function application

Writing the abstraction

Start on the outside

Design ⇒ Document ⇒ Implement

Name things clearly

Be consistent, re-use terms,
no kitchen sinks

Don’t leak internals

Don’t add features,
integrate

Some tips for writing the abstraction once you’ve found it

(step) Start on the outside: Decide the contract first, document it, and then implement it.
(step) Name things clearly:
- Pick a consistent naming scheme, and re-use terms for similar concepts of introducing new ones.
- For example, if you have UserDetails already, don’t introduce PostData — call it PostDetails. Each new term is a new thing a user has to incorporate into their mental model of the package.
- Oh and don’t create kitchen sink packages like 'util'. That’s what causes shallow and wide business code.
(step) Don’t leak the implementation. Define domain-specific data types, and expose those from your abstraction.
(step) Lastly, don’t just add a new feature. Features don’t exist in isolation. Consider how the new feature interacts with other features, and integrate it. Don’t just add an OmitSlash boolean, add a LinkStyle property.

Conclusion

Future-breaking code
leaks complexity,
causes disruption

Plan for expansion
Chaos to order early
Find the abstraction
Write deep modules
Flow in one direction

Future-Proof Go Packages

Hello!

Agenda

What makes a package future-proof?

Disruption

What causes disruption?

On complexity

Future-proofing packages

Planning for expansion

🧮 Expanding functions

Parameter objects

Parameter objects

Result objects

Result objects

Functional options

Functional options

Functional options

💡 Expanding abstractions

Accept interfaces

Accept interfaces

Accept interfaces

Return structs

Return structs

Planning for expansion

Finding and fixing problems

Built-in obsession

🧵 String overuse

🧵 String overuse

🧵 String overuse

🧵 String overuse

🧵 String overuse

🧵 String overuse

🗺️ Map overuse

🗺️ Map overuse

🗺️ Map overuse

🎂 Boolean overuse

🎂 Boolean overuse

🎂 Boolean overuse

🎂 Boolean overuse

➿ Callback overuse

➿ Callback overuse

➿ Callback overuse

Global state

🍝 Implicit process globals

🍝 Implicit process globals

🍝 Implicit process globals

Interface misuse

🥚 Premature interfaces

🥚 Premature interfaces

🥚 Premature interfaces

🦖 Big interfaces

🦖 Big interfaces

Follow the request path

Use functions

Use functions

Use functions

Build a strong core

Zooming out

🌊 Flow of information

🌊 Flow of information

🌊 Flow of information

🌊 Flow of information

🔍 Scope

🔍 Scope

🔍 Scope

Surface area

📦 Surface area and depth

📦 Surface area and depth

📦 Surface area and depth

📦 Surface area and depth

Finding the abstraction

🔭 Large scoped conditions

🔭 Large scoped conditions

🔭 Large scoped conditions

🚧 Partial function application

🚧 Partial function application

🚧 Partial function application

Writing the abstraction

Conclusion

See also

Accept `interface`s

Accept `interface`s

Accept `interface`s

Return `struct`s

Return `struct`s