Código legível / expressivo: O que você acha?

Assuntos Gerais Agile
#1

Estou lendo o livro Código Limpo do Robert C. Martin.
Isso tem causado algumas mudanças no código que gero…

Recentemente produzi uma linha onde mudei um pouco a forma com que estava acostumado a codificar e quero compartilhar com vocês e perguntar-lhes:

1 - O que acha desse código ?
2 - O quanto você entende ? Ficou claro o propósito desse código ?
3 - Se fosse traduzir para uma frase como ficaria ?

Dicas:
1 - Leia como se fosse um texto mesmo, não se preocupe como as coisas são feitas, o importante é entender O QUE esse código faz e não COMO faz.
2 - Leia “assertThat” como “Garanta que:”

Obrigado por opinar! :wink:

#2

Este livro deveria ser leitura obrigatória na faculdade.
Pois é complicado ver código mau feito e porco de ver.
O simples é mais fácil que o complicado. kkk
t+

#3

Ainda não terminei de ler este livro mas ele mudou radicalmente a forma de ver os códigos.
Minha opinião baseado no que já li…
No teu caso, acho que o código expressa o que pretende, mas seria interessante que os métodos dizessem melhor o que fazem .
Por ex, levando em consideração que

valor("abc") é um método, ele processa o valor,acrescenta ou modifica? Se vc tem um método/função, um verbo vai dizer exatamente o que ele faz.
Também na minha opinião, chamada de método que retorne valor pra ser usada como argumento de outro é perfeitamente normal mas quando vc usa vários no mesmo método prejudica a legibilidade o que vai de encontro com a filosofia do livro.

#4

Concordo com o que o luiz_renato disse, precisa de verbo para indicar a ação:

  • serializacao = serialize
  • metadado = criarMetadado, converterMetadado, paraMetadado

Porque se você observar o método JSON, ele pode ser tanto um método que avalia se é um JSON válido, que poderia ser isJSON, ou então uma conversão para JSON, que poderia ser toJSON. Dado o contexto dá para entender o método JSON, mas é sempre melhor deixar explicito.

E o que acabou acontecendo no seu código, é que tudo se encaixa perfeitamente neste contexto, mas fora dele os nomes dos métodos talvez não façam sentido ou não se encaixem bem, por falta do verbo. Os métodos tem nome de objetos, se fosse new Valor ao invés de só valor, faria mais sentido.

Mas veja, se você renomear os métodos para conter verbos, a sua frase não será mais confortavelmente legível.

Há um tropeço entre o garantaQue e serialize. E tirei o métodos id() e valor() por que não faziam sentido para mim.
Se você tiver varios tipos de metadado, pode alterar paraMetadadoChaveValor. Mas essa observação é de menor importância.

Concordo novamente com o luiz_renato na questão de se encadear vários métodos. Por mais que formando uma frase e ficando legível, ele parece mais difícil de dar manutenção.
Pense, é mais fácil entender um procedimento/raciocínio quando alguém te explica tudo de uma vez, ou quando explica passo a passo?

Serializado metadadoSerializado = serialize(paraMetadado(1, "abc")); JSON json = paraJson("metadado: {id: 1, valor: abc}"); //o que realmente importa, continuou a mesma frase assertThat(metadadoSerializado, is(json));

Acima, usei os nomes das variáveis para compor a frase.

Outra ponto, mas que não tem relação com o discutido, é que não sou a favor de programar em português. Por mais que seja nossa lingua nativa e ajude a entender termos mais complexos, o código SEMPRE vai misturar português com inglês, já que a API do Java e os frameworks são tudo em inglês. Fora que em inglês já temos alguns termos que são amplamente conhecidos, agilizando o entendimento.

Tudo acima é mera opinião pessoal e já faz um tempo que li um livro, então nada é muito confiável =p

Abraços

#5

Concordo com a ideia do código limpo, não só em sua descrição, mas também em relação a comentários em código, na mesma ideia do livro, se você precisa explicar o método é porque não esta bem escrito.

Estamos colocando em prática isso aqui na empresa e agiliza muito o raciocínio, só batendo o olho já é possível identificar o propósito da funcionalidade. Porém é necessário ter uma boa documentação de padrões para que todos os desenvolvedores sigam na mesma linha.

#6

É, eu comecei a ler esse livro mas preciso continuar. eh! eh!

#7

Guys desculpem a demora em responder.

Concordo com o que o luiz_renato e o Leandro Sole falaram, que os nomes dos métodos devem ser verbos que descrevam sua ação.

Mas usei substantivo para passar a ideia de que aquilo é um objeto!
Os médotos metadado(), id(), valor(), criam objetos que representam exatamente o nome do método, então quando faço metadado( id(1), valor(“abc”)), estou criando um metadado com id 1 e valor “abc”. Simples assim!

Esses métodos são exclusivos das classes de teste. No código de produção eles não existem, lá eu uso o construtor, obviamente. :smiley:
O propósito destes métodos é simplificar a leitura do código removendo coisas como “new” MetadodoXPTO(1L, “ABC”), ou seja, eliminei o new, o L de long e deixei muito claro que o metadado nestes caso é composto por id e valor.

Imagine se o valor fosse um número, o que acontece em outros testes, eu teria que fazer new MetadadoXPTO(1L, 2L).
Assim você precisaria conhecer a ordem dos parâmetros para saber se o id é 1 ou 2, assim como o valor.

Em vez disso preferi modificar a forma que o código é escrito e deixar claro qual numero é o id e qual é o valor, assim: metadado( id(1), valor(2)).

Essa idéia veio do groovy, onde você pode fazer determinar quais são os parametros, como no json.
Algo assim new MetadadoXPTO(id: 1, valor: 2);

Por fim, a ideia era deixar o código tão simples de ler quanto uma frase. Por isso pedi a vocês para traduzí-lo numa frase.

Então este código

pode ser lido assim:

"Garante que A serializacao DE UM metadado COM id 1 E valor “abc” é UM json COMO “metadado: {id: 1, valor: abc}”

Como podem perceber no português temos as preposições e artigos que dão maior sentido à frase.
Em inglês isso pode ser omitido e torna o texto direto e simplificado.
Se eu fosse criar métodos como a(), de(), um(), e(), a leitura ia ficar extamento como uma frase em português, mas o código não ia ficar muito limpo, então preferi não usar preposições e artigos.

O que percebi com base no feedback do pessoal, tanto do guj como da empresa, é que a leitura ficou sim simples, mas que é necessário um tempinho para adaptar-se à nova forma de leitura e que em poucos segundos as pessoas perceberam que os artigos e preposições estão implicitos na leitura.
Ou seja, o código apesar de estar formatado num padrão diferente é simples de entender e atingiu boa legibilidade e clareza, mas num primeiro instante é necessário adaptar-se.

Concordam com a minha conclusão ?

Obrigado.

#8

Acredito que não tenha lido todo o livro, logo vai perceber que também devemos evitar a passagem de métodos diretamente como parâmetros e minimizar a quantidade de argumentos das funções.
Segui os concelhos do livro, mas me tomei conta de outro grande problema com a legibilidade o nível de conhecimento da linguagem é um fator essêncial

#9