My Code Styleguide

Python

1. Format all code with black.

2. Put all code in functions. If you are writing a script, put the script in a function called main and call main() at the end of the script using the standard invocation:

   if __name__ == "__main__":
       main()
   

Golang

1. Any project that has more than 2 or 3 modules should use the uber/fx DI framework to keep things tidy.

2. Don't commit anything that hasn't been go fmt'd. The only exception is when committing things that aren't yet syntactically valid, which should only happen pre-v0.0.1 or on a non-main branch.

3. Even if you are planning to deal with only positive integers, use int/int64 types instead of uint/uint64 types. This is for consistency and compatibility with the standard library; it's better than casting all the time.

4. Try to use zerolog for logging. It's fast and has a nice API. For smaller/quick projects, the standard library's log package (and specifically log/slog) is fine. In that case, log structured logs whenever possible, and import sneak.berlin/go/simplelog to configure it appropriately. Example:

   package main
   
   import (
       "log/slog"
       _ "sneak.berlin/go/simplelog"
   )
   
   func main() {
       slog.Info("Starting up")
   }
   

5. Write at least a single test to check compilation. The test file can be empty, but it should exist. This is to ensure that go test ./... will always function as a syntax check at a minimum.

6. For anything beyond a simple script or tool, or anything that is going to run in any sort of "production" anywhere, make sure it passes golangci-lint.

7. Write a Dockerfile for every repo, even if it only runs the tests and linting. docker build . should always make sure that the code is in an able-to-be-compiled state, linted, and any tests run. The Docker build should fail if linting doesn't pass.

8. Include a Makefile with targets for at least clean and test. If there are multiple binaries, include a target for each binary. If there are multiple binaries, include a target for all that builds all binaries.

9. If you are writing a single-module library, .go files are okay in the repo root.

10. If you are writing a multi-module project, put all .go files in a pkg/ or internal/ directory. This is to keep the root clean and to make it easier to see what is a library and what is a binary.

11. Binaries go in cmd/ directories. Each binary should have its own directory. This is to keep the root clean and to make it easier to see what is a library and what is a binary. Only package main files should be in cmd/* directories.

12. Keep the main() function as small as possible.

13. Keep the main package as small as possible. Move as much code as is feasible to a library package.

14. HTTP HandleFuncs should be returned from methods or functions that need to handle HTTP requests. Don't use methods or our top level functions as handlers.

15. Provide a .gitignore file that ignores at least *.log, *.out, and *.test files, as well as any binaries.

16. Constructors should be called New() whenever possible. modulename.New() works great if you name the packages properly.

17. Don't make packages too big. Break them up.

18. Don't make functions or methods too big. Break them up.

19. Use descriptive names for functions and methods. Don't be afraid to make them a bit long.

20. Use descriptive names for modules and filenames. Avoid generic names like server. util is banned.

21. Constructors should take a Params struct if they need more than 1-2 arguments. Positional arguments are an endless source of bugs and should be avoided whenever possible.

22. Use context.Context for all functions that need it. If you don't need it, you can pass context.Background(). Anything long-running should get and abide by a Context. A context does not count against your number of function or method arguments for purposes of calculating whether or not you need a Params struct, because the ctx is always first.

23. Contexts are always named ctx.

24. Use context.WithTimeout or context.WithDeadline for any function that could potentially run for a long time. This is especially true for any function that makes a network call. Sane timeouts are essential.

25. Avoid global state, especially global variables. If you need to store state that is global to your launch or application instance, use a package globals or appstate with a struct and a constructor and require it as a dependency in your constructors. This will allow consumers to be more easily testable and will make it easier to reason about the state of your application. Alternately, if your dependency graph allows for it, put it in the main struct/object of your application, but remember that this harms testability.

26. Package-global "variables" are ok if they are constants, such as static strings or integers or errors.

27. Whenever possible, avoid hardcoding numbers or values in your code. Use descriptively-named constants instead. Recall the famous SICP quote: "Programs must be written for people to read, and only incidentally for machines to execute." Rather than comments, a descriptive constant name is much cleaner.

    Example:

    
    const jsonContentType = "application/json; charset=utf-8"
    
    func (s *Handlers) respondJSON(w http.ResponseWriter, r *http.Request, data interface{}, status int) {
         w.WriteHeader(status)
         w.Header().Set("Content-Type", jsonContentType)
         ...
     }
    

28. Define your struct types near their constructors.

29. Define your interface types near the functions that use them, or if you have multiple conformant types, put the interface(s) in their own file.

30. Define errors as package-level variables. Use a descriptive name for the error. Use errors.New to create the error. If you need to include additional information in the error, use a struct that implements the error interface.

31. Use lowerCamelCase for local function/variable names. Use UpperCamelCase for type names, and exported function/variable names. Use snake_case for JSON keys. Use lowercase for filenames.

32. Explicitly specify UTC for datetimes unless you have a very good reason not to. Use time.Now().UTC() to get the current time in UTC.

33. String dates should always be ISO8601 formatted. Use time.Time.Format with time.RFC3339 to get the correct format.

34. Use time.Time for all date and time values. Do not use int64 or string for dates or times internally.

35. When using time.Time in a struct, use a pointer to time.Time so that you can differentiate between a zero value and a null value.

36. Use time.Duration for all time durations. Do not use int64 or string for durations internally.

37. When using time.Duration in a struct, use a pointer to time.Duration so that you can differentiate between a zero value and a null value.

38. Whenever possible, in argument types and return types, try to use standard library interfaces instead of concrete types. For example, use io.Reader instead of *os.File. Tailor these to the needs of the specific function or method. Examples:

    • io.Reader instead of *os.File:

      • io.Reader is a common interface for reading data, which can be implemented by many types, including *os.File, bytes.Buffer, strings.Reader, and network connections like net.Conn.

    • io.Writer instead of *os.File or *bytes.Buffer:

      • io.Writer is used for writing data. It can be implemented by *os.File, bytes.Buffer, net.Conn, and more.

    • io.ReadWriter instead of *os.File:

      • io.ReadWriter combines io.Reader and io.Writer. It is often used for types that can both read and write, such as *os.File and net.Conn.

    • io.Closer instead of *os.File or *net.Conn:

      • io.Closer is used for types that need to be closed, including *os.File, net.Conn, and other resources that require cleanup.

    • io.ReadCloser instead of *os.File or http.Response.Body:

      • io.ReadCloser combines io.Reader and io.Closer, and is commonly used for types like *os.File and http.Response.Body.

    • io.WriteCloser instead of *os.File or *gzip.Writer:

      • io.WriteCloser combines io.Writer and io.Closer. It is used for types like *os.File and gzip.Writer.

    • io.ReadWriteCloser instead of *os.File or *net.TCPConn:

      • io.ReadWriteCloser combines io.Reader, io.Writer, and io.Closer. Examples include *os.File and net.TCPConn.

    • fmt.Stringer instead of implementing a custom String method:

      • fmt.Stringer is an interface for types that can convert themselves to a string. Any type that implements the String() string method satisfies this interface.

    • error instead of custom error types:

      • The error interface is used for representing errors. Instead of defining custom error types, you can use the errors.New function or the fmt.Errorf function to create errors.

    • net.Conn instead of *net.TCPConn or *net.UDPConn:

      • net.Conn is a generic network connection interface that can be implemented by TCP, UDP, and other types of network connections.

    • http.Handler instead of custom HTTP handlers:

      • http.Handler is an interface for handling HTTP requests. Instead of creating custom handler types, you can use types that implement the ServeHTTP(http.ResponseWriter, *http.Request) method.

    • http.HandlerFunc instead of creating a new type:

      • http.HandlerFunc is a type that allows you to use functions as HTTP handlers by implementing the http.Handler interface.

    • encoding.BinaryMarshaler and encoding.BinaryUnmarshaler instead of custom marshal/unmarshal methods:

      • These interfaces are used for binary serialization and deserialization. Implementing these interfaces allows types to be encoded and decoded in a standard way.

    • encoding.TextMarshaler and encoding.TextUnmarshaler instead of custom text marshal/unmarshal methods:

      • These interfaces are used for text-based serialization and deserialization. They are useful for types that need to be represented as text.

    • sort.Interface instead of custom sorting logic:

      • sort.Interface is an interface for sorting collections. By implementing the Len, Less, and Swap methods, you can sort any collection using the sort.Sort function.

    • flag.Value instead of custom flag parsing:

      • flag.Value is an interface for defining custom command-line flags. Implementing the String and Set methods allows you to use custom types with the flag package.

39. Avoid using panic in library code. Instead, return errors to allow the caller to handle them. Reserve panic for truly exceptional conditions.

40. Use defer to ensure resources are properly cleaned up, such as closing files or network connections. Place defer statements immediately after resource acquisition.

41. When calling a function with go, wrap the function call in an anonymous function to ensure it runs in the new goroutine context:

    Right:

    go func() {
        someFunction(arg1, arg2)
    }()
    

    Wrong:

    go someFunction(arg1, arg2)
    

42. Use iota to define enumerations in a type-safe way. This ensures that the constants are properly grouped and reduces the risk of errors.

    Example:

    
    type HandScore int
    
    const (
        ScoreHighCard = HandScore(iota * 100_000_000_000)
        ScorePair
        ScoreTwoPair
        ScoreThreeOfAKind
        ScoreStraight
        ScoreFlush
        ScoreFullHouse
        ScoreFourOfAKind
        ScoreStraightFlush
        ScoreRoyalFlush
    )
    

    Example 2:

    type ByteSize float64
    
    const (
        _           = iota // ignore first value by assigning to blank identifier
        KB ByteSize = 1 << (10 * iota)
        MB
        GB
        TB
        PB
        EB
        ZB
        YB
    )
    

43. Don't hardcode big lists of things in your normal code. Either isolate lists in their own module/package and write some getters, or use a third party library. For example, if you need a list of country codes, you can use https://github.com/emvi/iso-639-1. It's okay to embed a data file (use go embed) in your binary if you need to, but make sure you parse it once as a singleton and don't read it from disk every time you need it. Don't use too much memory for this, embedding anything more than perhaps 25MiB (uncompressed) is probably too much. Compress the file before embedding and uncompress during the reading/parsing step for efficiency.

44. When storing numeric values that represent a number of units, either include the unit in the variable name (e.g. uptimeSeconds, delayMsec, coreTemperatureCelsius), or use a type alias (that includes the unit name), or use a 3p library such as github.com/alecthomas/units for SI/IEC byte units, or github.com/bcicen/go-units for temperatures (and others). The type system is your friend, use it.

45. Once you have a working program, run go mod tidy to clean up your go.mod and go.sum files. Tag a v0.0.1 or v1.0.0. Push your main branch and tag(s). Subsequent work should happen on branches so that main is "always releasable". "Releasable" in this context means that it builds and functions as expected, and that all tests and linting passes.

Other Golang Tips and Best Practices (Optional)

1. When passing channels to goroutines, use read-only (<-chan) or write-only (chan<-) channels to communicate the direction of data flow clearly.

2. Use io.MultiReader to concatenate multiple readers and io.MultiWriter to duplicate writes to multiple writers. This can simplify the handling of multiple data sources or destinations.

3. For simple counters and flags, use the sync/atomic package to avoid the overhead of mutexes.

4. When using mutexes, minimize the scope of locking to reduce contention and potential deadlocks. Prefer to lock only the critical sections of code. Try to encapsulate the critical section in its own function or method. Acquire the lock as the first line of the function, defer release of the lock as the second line of the function, and lines 3-5 should perform the task. Try to keep it as short as possible. Avoid using mutexes in the middle of a function. In short, build atomic functions.

5. Design types to be immutable where possible. This can help avoid issues with concurrent access and make the code easier to reason about.

6. Global state can lead to unpredictable behavior and makes the code harder to test. Use dependency injection to manage state.

7. Avoid using init functions unless absolutely necessary as they can lead to unpredictable initialization order and make the code harder to understand.

8. Provide comments for all public interfaces explaining what they do and how they should be used. This helps other developers understand the intended use.

9. Be mindful of resource leaks when using time.Timer and time.Ticker. Always stop them when they are no longer needed.

10. Use sync.Pool to manage a pool of reusable objects, which can help reduce GC overhead and improve performance in high-throughput scenarios.

11. Avoid using large buffer sizes for channels. Unbounded channels can lead to memory leaks. Use appropriate buffer sizes based on the application's needs.

12. Always handle the case where a channel might be closed. This prevents panic and ensures graceful shutdowns.

13. For small structs, use value receivers to avoid unnecessary heap allocations. Use pointer receivers for large structs or when mutating the receiver.

14. Only use goroutines when necessary. Excessive goroutines can lead to high memory consumption and increased complexity.

15. Use sync.Cond for more complex synchronization needs that cannot be met with simple mutexes and channels.

16. Reflection is powerful but should be used sparingly as it can lead to code that is hard to understand and maintain. Prefer type-safe solutions.

17. Avoid storing large or complex data in context. Context should be used for request-scoped values like deadlines, cancellation signals, and authentication tokens.

18. Use runtime.Callers and runtime.CallersFrames to capture stack traces for debugging and logging purposes.

19. Use the testing.TB interface to write helper functions that can be used with both *testing.T and *testing.B.

20. Use struct embedding to reuse code across multiple structs. This is a form of composition that can simplify code reuse.

21. Prefer defining explicit interfaces in your packages rather than relying on implicit interfaces. This makes the intended use of interfaces clearer and the code more maintainable.

Author

@sneak <sneak@sneak.berlin>

License

WTFPL

Do with it what you will. There is no warranty, express or implied, including but not limited to merchantability or fitness for a particular purpose. Use at your own risk.