Boas Práticas & Clean Code com Go

BIANCA ROSA

Agenda

  • Nomenclaturas e convenções
    • Nomes de variáveis
    • Nomes de pacotes
    • Nomes de funções
    • Nomes de interfaces
    • Comentários
  • Conceitos de Clean Code
    • Regra do Escoteiro
    • SRP
    • DRY
  • O cinto de ferramentas do desenvolvedor Go
  • O que não fazer
  • Referências

Nomenclaturas e convenções

There are only two hard things in Computer Science: cache invalidation and naming things.

Phil Karlton

Nomes de variáveis

  • Lower case, se necessário utilize mixedCaps.
     
  • Regra básica: crescem e se tornam mais descritivos de acordo com o tamanho do escopo.
     
  • Pequenos e abreviados quando usados em blocos de escopo menores.
     
  • Podem ser mais descritivos em blocos de escopo maiores.

Exemplos

  • req vs request
  • res vs response
  • c vs counter
  • n vs number
  • s vs string
  • i vs loopIndex
  • addr vs address

Como assim "tamanho do escopo"?

O escopo de uma variável é definido pelo momento da sua declaração até o último momento em que ela pode ser utilizada.

 

Um pacote é um escopo MUITO grande para variáveis com nomes muito pequenos.

Cuidado!

Escreva código para humanos.

 

A idéia de encurtar nomes é para facilitar e não para gerar complexidade.

Nomes de pacotes

  • Lower case, uma única palavra: sem underscore ou mixedCaps.
     
  • Use nomes de pacotes que vão fazer sentido na chamada da sua função.

Colisão de nome de pacotes

Pode acontecer.

Quem nunca acabou parando com dois pacotes utils e quando foi importar, se viu com um problema?

Dica: deixe o pacote com o nome que faz sentido pra ele e delegue a responsabilidade de nomear o pacote no momento da importação.

Exemplo

import "io"
import "bufio"
import "ring"

ring := ring.New()
var reader *io.Reader
var bufreader *bufio.Reader

Nomes de funções

  • Seguem a mesma regra de variáveis: mixedCaps ou MixedCaps.
     
  • Seja descritivo.
     
  • Seja conciso.

Exemplo

obj.Owner()

obj.SetOwner(owner)

Nomes de interfaces

  • Em interfaces de um único método, o nome, por convenção, é adotado como o nome do método + o sufixo -er (exemplo: Reader, Writter, Formatter, Notifier)

Exemplo

type Caller interface {
	Call()
}

type Notifier interface {
	Notify()
}

Escrevendo comentários

  • Evite escrever comentários para explicar lógica e código. Ao invés disso, invista em nomes de funções que façam sentido.
     
  • A grande utilidade de comentários é a geração de doc automáticas através do go doc.

Echo - Context

type (
	// Context represents the context of the current HTTP request. It holds request and
	// response objects, path, path parameters, data and registered handler.
	Context interface {
		// Request returns `*http.Request`.
		Request() *http.Request

		// SetRequest sets `*http.Request`.
		SetRequest(r *http.Request)

		// SetResponse sets `*Response`.
		SetResponse(r *Response)

		// Response returns `*Response`.
		Response() *Response

		// IsTLS returns true if HTTP connection is TLS otherwise false.
		IsTLS() bool

		// IsWebSocket returns true if HTTP connection is WebSocket otherwise false.
		IsWebSocket() bool

		// Scheme returns the HTTP protocol scheme, `http` or `https`.
		Scheme() string

		// RealIP returns the client's network address based on `X-Forwarded-For`
		// or `X-Real-IP` request header.
		RealIP() string

		// Path returns the registered path for the handler.
		Path() string

		// SetPath sets the registered path for the handler.
		SetPath(p string)

		// Param returns path parameter by name.
		Param(name string) string

		// ParamNames returns path parameter names.
		ParamNames() []string

		// SetParamNames sets path parameter names.
		SetParamNames(names ...string)

		// ParamValues returns path parameter values.
		ParamValues() []string

		// SetParamValues sets path parameter values.
		SetParamValues(values ...string)

		// QueryParam returns the query param for the provided name.
		QueryParam(name string) string

		// QueryParams returns the query parameters as `url.Values`.
		QueryParams() url.Values

		// QueryString returns the URL query string.
		QueryString() string

		// FormValue returns the form field value for the provided name.
		FormValue(name string) string

		// FormParams returns the form parameters as `url.Values`.
		FormParams() (url.Values, error)

		// FormFile returns the multipart form file for the provided name.
		FormFile(name string) (*multipart.FileHeader, error)

		// MultipartForm returns the multipart form.
		MultipartForm() (*multipart.Form, error)

		// Cookie returns the named cookie provided in the request.
		Cookie(name string) (*http.Cookie, error)

		// SetCookie adds a `Set-Cookie` header in HTTP response.
		SetCookie(cookie *http.Cookie)

		// Cookies returns the HTTP cookies sent with the request.
		Cookies() []*http.Cookie

		// Get retrieves data from the context.
		Get(key string) interface{}

		// Set saves data in the context.
		Set(key string, val interface{})

		// Bind binds the request body into provided type `i`. The default binder
		// does it based on Content-Type header.
		Bind(i interface{}) error

		// Validate validates provided `i`. It is usually called after `Context#Bind()`.
		// Validator must be registered using `Echo#Validator`.
		Validate(i interface{}) error

		// Render renders a template with data and sends a text/html response with status
		// code. Renderer must be registered using `Echo.Renderer`.
		Render(code int, name string, data interface{}) error

		// HTML sends an HTTP response with status code.
		HTML(code int, html string) error

		// HTMLBlob sends an HTTP blob response with status code.
		HTMLBlob(code int, b []byte) error

		// String sends a string response with status code.
		String(code int, s string) error

		// JSON sends a JSON response with status code.
		JSON(code int, i interface{}) error

		// JSONPretty sends a pretty-print JSON with status code.
		JSONPretty(code int, i interface{}, indent string) error

		// JSONBlob sends a JSON blob response with status code.
		JSONBlob(code int, b []byte) error

		// JSONP sends a JSONP response with status code. It uses `callback` to construct
		// the JSONP payload.
		JSONP(code int, callback string, i interface{}) error

		// JSONPBlob sends a JSONP blob response with status code. It uses `callback`
		// to construct the JSONP payload.
		JSONPBlob(code int, callback string, b []byte) error

		// XML sends an XML response with status code.
		XML(code int, i interface{}) error

		// XMLPretty sends a pretty-print XML with status code.
		XMLPretty(code int, i interface{}, indent string) error

		// XMLBlob sends an XML blob response with status code.
		XMLBlob(code int, b []byte) error

		// Blob sends a blob response with status code and content type.
		Blob(code int, contentType string, b []byte) error

		// Stream sends a streaming response with status code and content type.
		Stream(code int, contentType string, r io.Reader) error

		// File sends a response with the content of the file.
		File(file string) error

		// Attachment sends a response as attachment, prompting client to save the
		// file.
		Attachment(file string, name string) error

		// Inline sends a response as inline, opening the file in the browser.
		Inline(file string, name string) error

		// NoContent sends a response with no body and a status code.
		NoContent(code int) error

		// Redirect redirects the request to a provided URL with status code.
		Redirect(code int, url string) error

		// Error invokes the registered HTTP error handler. Generally used by middleware.
		Error(err error)

		// Handler returns the matched handler by router.
		Handler() HandlerFunc

		// SetHandler sets the matched handler by router.
		SetHandler(h HandlerFunc)

		// Logger returns the `Logger` instance.
		Logger() Logger

		// Echo returns the `Echo` instance.
		Echo() *Echo

		// Reset resets the context after request completes. It must be called along
		// with `Echo#AcquireContext()` and `Echo#ReleaseContext()`.
		// See `Echo#ServeHTTP()`
		Reset(r *http.Request, w http.ResponseWriter)
	}

	context struct {
		request  *http.Request
		response *Response
		path     string
		pnames   []string
		pvalues  []string
		query    url.Values
		handler  HandlerFunc
		store    Map
		echo     *Echo
		lock     sync.RWMutex
	}
)

Conceitos de Clean Code

Regra do Escoteiro

The Boy Scout Rule

Ao sair da área onde você estava acampado, deixe-a mais limpa do que quando a encontrou.

Ou seja...

  • Se você está mexendo num arquivo que tem um typo, corrija-o.
  • Se o nome dessa variável poderia ser melhor, refatore.
  • Se você está escrevendo testes para uma função e tem uma função não testada logo ao lado, escreva mais um teste!

Se você nunca fizer um pouquinho a mais pra melhorar seu código, ele não melhora sozinho.

Princípio da Responsabilidade Única (SRP)

type fox struct{}
                      
func (f *fox) Say() {
  fmt.Println("Ring-ding-ding-ding-dingeringeding!")
}
type fox struct{}
                      
func (f *fox) Say() {
  fmt.Println("Ring-ding-ding-ding-dingeringeding!")
}

func (f *fox) Meow() {
  fmt.Println("Meow-meow-meow-meow-meow-meow")
}
type fox struct{}
          
func (f *fox) Say() {
  fmt.Println("Ring-ding-ding-ding-dingeringeding!")
}

type cat struct{}

func (c *cat) Meow() {
  fmt.Println("Meow-meow-meow-meow-meow-meow")
}

DRY

Don't Repeat Yourself

Copiar e colar código ou escrever códigos muito parecidos é um sinal de que algo pode estar errado.

Criar códigos complexos para não copiar ou reescrever códigos simples é um sinal de algo está ainda mais errado.

O cinto de ferramentas do desenvolvedor Go

Tools

  • fmt
  • vet
  • pprof

O que não fazer

func converte(s string) int {
  n, _ := strconv.Atoi(s)
  return n
}

Sempre cheque seus erros!

Ops.

Referências Legais

0brigada!

Boas Práticas & Clean Code com Go

By Bianca Rosa

Boas Práticas & Clean Code com Go

  • 1,734