# go-ceph Mission Statement Brainstorming ## Motivation In the sake for our consistency, we should choose and agree on a kind of mission statement. That might make it easier for us to decide between various alternatives while extending or refactoring the library and keep an eye on the "big picture". ## Aspects that could go into the statement ### Possible criteria * Usability * Go style and idioms * Are there established best practices of Go libraries, that we can refer to? * ... * Completeness * Scope - What do we cover? * librados * librbd * libcephfs * ... * Performance * When is it adequate to prefer "worse" code (readability, maintainability, usability) for better performance. * Code Style * Any code style that we can adopt? Something like https://google.github.io/styleguide/cppguide.html but for Go? * There is https://github.com/golang/go/wiki/CodeReviewComments but it's not a real style guide. * Do we need one? It can help to shorten bikeshedding by just sticking to one style. * ... ### High level vs. low level * High level * Convenience functions (several C-APIs) * Go idiomatic * ... * Low level * Close to C-API * possibly more performant * ... * Possible approaches * Bottom up * Follows the natural development flow, because high level funtions would later use the already impplemented low level functions * Top down * Let's the Go consumers first have a familiar interface. Low level functions stay private first. Can be extended on demand with exported low level functions if useful/necessary. ## JJM's Notes Because I didn't want to mess with your exsiting brainstorm notes and wanted to add my a few of my own: * General thoughts * I want to expose the "full power" of the Ceph APIs * With convient abstractions for the Go programmer when appropriate * IOW, don't hide stuff that exists in Ceph from Go code * But where no conflicts exist, use naming, style, types, etc. that are familar to a Go programmer * "We read the Ceph docs (and code) and manpages so you don't have to!" :-) * General guideslines for (new) APIs * Use doc comments (see "Implements:") to help users match up our APIs with those in lib{cephfs,rados,rbd} * Unlike in C we can create "trivial types" to act as guard rails and avoid passing invalid values and flags to functions * Avoid adding names that exist in common Go standard library packages that don't accept or return the same types. * A good example is the "os" package. Don't add `File.Zapp(int) uint64` if the File type in os is `File.Zapp() int64`. * If the former's signature is needed to fully express the API Ceph provides, give it a less-common name. * IFF there's no conflict at all, prefer the Go stdlib naming. * I am personally OK with a little duplication (aka clutter) to continue to provide both power and convenience. ## Mission Statement Draft *[let's draft and develop a statement here]*