zygotecnologia / guides Goto Github PK

Adicionar exemplos de como utilizar o compartilhamento código. Onde podemos distribuir métodos ou constantes comuns entre várias classes, objetos e módulos. Incluir exemplos usando include e extend.

Tem uma diferença na forma de adicionar o método e como é dado o output em caso de erro ou se usar o format de documentation para rodar os testes, e também tem uma diferença na chamada

https://stackoverflow.com/questions/19556296/whats-the-difference-between-include-examples-and-it-behaves-like

Exemplo: https://github.com/zygotecnologia/bonuz-api/pull/2968

Vejo três possibilidades:

def example_a
   return 1, 2
end

def example_b
   return [1, 2]
end

def example_c
   return OpenStruct.new(foo: 1, bar: 2)
end

Os retornos de example_a e example_b são os mesmos.

example_a # `[1, 2]`
example_b # `[1, 2]`
example_a.class # `Array`
example_b.class # `Array`

Se o objetivo é simplesmente fazer a "desestruturação" do valor que está sendo retornado por um método privado da classe, acho a opção example_a mais óbvio.

z, y = example_a

Mas se começamos a fazer algo como um ternário com o valor que queremos retornar, não é possível escrever o método como no example_a. Precisamos colocar os [].

def example_d(b)
  return b ? 1,2 : 3,4
# `SyntaxError: unexpected ',', expecting ':'`

def example_d(b)
  return b ? [1,2] : [3,4]
end

z, y = example_d(true)
w, x = example_d(false)

Para tornar isso mais consistente, independente de estarmos fazendo algo como um ternário ou não, acho a opção example_b melhor.

Mas, acho as opções example_a e exampl_b apenas válidas para métodos privados de uma classe. Acho estranho dependermos de saber a posição dos retornos dos métodos do lado de fora dela. Para isso acho o example_c mais claro.

class GameStatsCalculator
  def call_a
    goals, winner, ball_possession, fouls
  end

  def call_b
    [goals, winner, ball_possession, fouls]
  end

  def call_c
    OpenStruct.new(goals: goals,
                   winner: winner,
                   ball_possession: ball_possession,
                   fouls: fouls)
  end
  ...
end

Poderiamos discutir também para ter um _ na frente do nome da variável.

Sobre escrever em inglês, português ou ambos. Uma estratégia comum é encontrar algo como:

README.md <- apenas links para as diferentes linguagens
README.en.md <- em inglês.
README.pt-br.md <- em português.

Acho que talvez seja overkill pq também temos que ficar sincronizando os exemplos entre os diferentes arquivos.

Mas acho que fica super confuso se escrevermos tudo no mesmo arquivo...

Pessoalmente acho que devemos escolher uma língua e fazer tudo nela. Sem grandes opiniões entre fazer tudo em inglês ou fazer tudo em português.

Alguns pontos que pensei:

• Tem um monte de guides de linguagens em inglês por aí, talvez "ganhamos" algo por ser um dos poucos que poderia ser em português.

• É super difícil traduzir alguns conceitos para português.

  • Um exemplo de ruby: Inline if modifier, seria algo como modificador de condição em linha? condição no fim da linha? etc.

Quando temos que rodar um teste de feature com javascript, colocar js: true em um context ou describe causa o carregamento do ambiente de testes de javascript para todos os exemplos presentes ali, independente se um exemplo não precise rodar com javascript. Utilizar js: true na definição do it/example garante que apenas os que têm a real necessidade de javascript vão utilizar esse ambiente.

Por outro lado, contextos bem separados e organizados poderiam se beneficiar de apenas um js: true definido, assim fica sabido que todo caso ali presente usa javascript

agora que a primeira versão do guide está finalizada, precisamos montar uma estrutura lógica e organizar o markdown para facilitar a busca por regras.

Em quais casos um método helper na controller é aceitável?

class ApplicationController < ActionController::Base    
  helper_method :method

  def method
    ... #your code
  end
end

Simplificar os nomes das branches e usar / para separar significados e - para espaçamento.
Ex: whitelabel/bugfix/blank-offer
zygo/new/feature/mgm
api/new/endpoint/debit
api/bugfix/endpoint/debit

Adicionar no nosso guia de Rails sobre não passar objetos(User, Brand, Store, etc) para um job do sidekiq. Passar apenas o ID no caso de ser um modelo. Outro exemplo interessante é passar uma data, teria que ser convertida em string antes de passar para lá, e "desconverter" dentro do worker, o iso8601 é bom para isso.

Sei que tem isso especificado em algum lugar da documentação do sidekiq explicando todos os detalhes, mas não encontrei. Acho que é legal conseguirmos esse link para colocar lá tbm.

# GOOD
class GoodReleaseStoreWorker
  include Sidekiq::Worker

  def perform(store_id, moment)
    store = Store.find(store_id)
    moment = moment.to_datetime

    return if moment.saturday? || moment.sunday?

    store.update(released_at: moment)
  end
end

GoodReleaseStoreWorker.perform_async(Store.last.id, Time.zone.now.iso8601)


# BAD
class BadReleaseStoreWorker
  include Sidekiq::Worker

  def perform(store, moment)
    return if moment.saturday? || moment.sunday?

    store.update(released_at: moment)
  end
end

BadReleaseStoreWorker.perform_async(Store.last, Time.zone.now)

Ao garantir que algum elemento, como um botão, não esteja presente em uma tela, podemos utilizar um seletor precedido de um not_to, como por exemplo expect(page).not_to have_button("Salvar"). Porém, isso causa um atraso no teste, pois o capybara espera alguns segundos para ter certeza que o botão realmente não vai aparecer. Utilizando negative selectors (e.g. expect(page).to have_no_button), esse atraso não acontece.

Uma terceira alternativa seria não utilizar negativas de nenhum tipo, e apenas garantir os elementos que aparecem na tela.

Para os nossos outros repositórios, e o repositório de guides.
Já entraria no nosso style guide de git.

#6 (comment)