Um jogo para ajudar a visualizar os efeitos do estilo de colocação de chaves em Java

O objetivo é ser objetivo

Vários anos atrás, criei uma abordagem criativa para ajudar a estabelecer e concordar com o estilo de codificação com uma nova equipe na qual estava trabalhando. Estávamos nos estágios iniciais de codificação em um novo projeto usando a linguagem de programação Java. Solicitei que decidíssemos e concordássemos com diretrizes de estilo de código consistentes como uma equipe, desde o início. Eu sabia que precisava apresentar um argumento objetivo e criativo para abordar um dos debates controversos sobre estilo de código em Java — onde colocar as chaves.

Escolhendo a criatividade ao invés do conflito

Nadar contra a maré do “mas todo mundo faz assim” é difícil. É ainda mais difícil quando uma empresa de pesquisa altamente respeitada carimba seu selo de aprovação em um determinado estilo de codificação Java.

Para me ajudar a apresentar um argumento objetivo para um determinado estilo de colocação de braquetes, criei um jogo que chamei de “Connect the Braces”. Peguei o código de duas classes de exemplo que criei e colei em uma apresentação do Powerpoint e literalmente desenhei linhas na parte superior do código para conectar as chaves iniciais e finais. O jogo foi inspirado em um dos meus jogos de infância favoritos - “Connect the Dots”.

O melhor de “Ligue os pontos” é que as regras são simples e quase todo mundo já jogou na escola. “Conectar o aparelho” também é muito simples. Basta conectar as chaves iniciais e finais de cada escopo de código desenhando uma linha entre elas. Fácil.

Apresentei o jogo para a equipe e, depois que terminei, ninguém respondeu “mas todo mundo faz assim”. Isso confirmou que pelo menos uma equipe respondeu bem a um argumento criativo sobre o estilo de colocação do colete.

Automatizando o jogo

Contei ao meu amigo Vladimir Zakharov (Vlad) sobre este jogo e como ele efetivamente desarmou o que eu havia experimentado anteriormente como um debate incendiário. Perguntei a Vlad se ele poderia escrever algum código Java para visualizar o jogo que descrevi para ele. Vlad é melhor em programação visual do que eu, então eu sabia que ele completaria o código mais rápido do que eu.

Vlad fez algo ainda melhor do que apenas conectar as chaves em um arquivo de origem. Ele também coloriu blocos de código em destaque verde. Isso tem o benefício adicional de realçar visualmente os espaços em branco.

As imagens na seção a seguir foram geradas usando a versão automatizada de Vlad de “Connect the Braces” no código real do Eclipse Collections Kata .

Aviso! Jogo!

As imagens a seguir são gráficas. Alguns desenvolvedores podem considerá-los perturbadores. O código-fonte real foi usado na criação dos visuais a seguir. Quaisquer imagens que não possam ser vistas depois de rolar além deste texto são de responsabilidade exclusiva da pessoa que está rolando, não do autor. Quaisquer frutas ou animais de estimação que foram danificados durante as duas rodadas de "Conectar os aparelhos" foram o resultado de escolhas de estilo de código, não do autor. Escolha sabiamente. Você foi avisado!

Primeira Rodada: Fruit Enum

Segunda Rodada: Enum PetType

Escolhendo Clareza em vez de Desordem

Eu sei que provavelmente acabei de entrar em um rio caudaloso cheio de piranhas famintas enquanto usava um calção de banho feito de bife. Não pretendo convencer a todos de que um determinado estilo de colocação de órteses é o “único estilo verdadeiro”. Definitivamente, há um estilo que prefiro quando escrevo código e tenho que defendê-lo em todos os projetos em que trabalho. Acho que quando apresento meu argumento usando este jogo, podemos ter uma discussão saudável sobre a importância da estética, do espaço em branco e do rastreamento visual para leitura e leitura do código.

Eu escolho clareza em vez de desordem. Sinal sobre ruído. Eu escolho o estilo à direita.

Para citar meu amigo Vlad:

Quando leio o código, geralmente quero ver o “o quê”, por exemplo, quais são as responsabilidades dessa classe, qual é o contrato desse método, qual é a condição para acionar essa ramificação — ou o “como”, por exemplo, como esse método faz o que faz, o que acontece se eu seguir esse ramo e assim por diante. Ter o que é e o como visualmente segregado me ajuda a escanear o código e focar minha atenção no que importa no momento.

O estilo de formatação de chaves verticais tem um efeito natural de separar claramente o “o quê” do “como” introduzindo um espaço em branco entre a assinatura (definições de classe e método) e a implementação (variáveis ​​e código). As chaves iniciais e finais estão sempre no mesmo local horizontal, com variabilidade baseada consistentemente na profundidade dos escopos aninhados (por exemplo, instruções de controle como if, for e while). Você espera ver a base de uma forma de pirâmide com os colchetes, então pode ignorar com segurança onde eles estão, porque você sabe onde eles estão. Este estilo é fácil de implementar formatação automática em seu IDE e aplicar em uma compilação CheckStyle.

Eu tenho nadado contra a maré usando este estilo de formatação em Java por mais de 20 anos. Para os desenvolvedores que precisam ler ou trabalhar nas bases de código que são formatadas usando o estilo de colocação de chaves verticais por minha causa, tenho algo a dizer.

De nada!

Uma exceção à regra

Eu escolho um estilo diferente de colocação de colchetes ao criar slides do Powerpoint ou texto para um livro com código Java. Nessas duas mídias impressas apenas, quase sempre escolho o estilo que favorece menos linhas de código. Quebrar o código nas páginas é indesejável. Esta é uma compensação feita devido aos limites do espaço vertical disponível. Esse limite imposto não existe no código que você está lendo em seu IDE ou em uma fonte de leitura de navegador de um VCS como GitHub ou GitLab, onde a rolagem vertical funciona perfeitamente.

Sete hábitos de codificação ineficazes de muitos programadores

Alguns meses depois de criar o jogo “Connect the Braces”, me deparei com uma palestra incrível de Kevlin Henney, que apresenta um ótimo argumento para um estilo específico de colocação de chaves, entre muitos outros pontos importantes que ele faz na palestra sobre estilo de codificação.

Portanto, o que acabei de dizer, caso você esteja se perguntando, sim, existe uma maneira de determinar a maneira correta de alinhar seu aparelho... de forma objetiva.

Não há spoilers. Eu recomendo assistir a esta palestra. Atenção, esta palestra pode ser uma interrupção construtiva em seu estilo de codificação atual.

Uma chamada à ação no estilo de código Java

Estamos deixando bilhões de linhas de código-fonte Java em sistemas de controle de versão para serem mantidos por nós mesmos e futuras gerações de desenvolvedores. O estilo do código tem um impacto direto e sutil na clareza e legibilidade. Nem todo mundo lê o código na mesma velocidade. Pode haver desafios de acessibilidade que você deve discutir e considerar como uma equipe. Todos devem ser capazes de analisar o código eventualmente lendo-o, independentemente do estilo do código. Se pudéssemos gastar menos ciclos separando o quê do como e encontrando o código que estamos procurando, seria bom.

Aqui estão minhas regras para construir um estilo de codificação aceitável em uma equipe.

1. Converse com sua equipe sobre as diretrizes de estilo de código.
2. Aplique diretrizes de estilo de código consistentes em seu projeto usando regras de formatação automática codificadas e personalizadas em seu IDE favorito.
3. Execute uma compilação contínua automatizada que será interrompida em confirmações de estilo de código inconsistentes (por exemplo, CheckStyle).
4. Publique suas diretrizes de estilo de código em seu projeto VCS.
5. Tenha coragem e reserve um tempo para desenvolver suas diretrizes de estilo de código quando descobrir ou aprender algo novo.

Sinta-se à vontade para usar o jogo Connect the Braces para ajudar a facilitar discussões racionais e objetivas sobre estilo de código, especialmente no que se refere a discussões sobre estilo de colocação de chaves em Java. Se você gosta desse estilo e deseja ver as configurações de estilo de código que usamos no IntelliJ IDEA para coleções do Eclipse nos últimos sete anos, elas são verificadas no GitHub aqui .

Aproveitar!

Eu sou o criador e um Committer para o projeto Eclipse Collections OSS que é gerenciado na Eclipse Foundation . Eclipse Collections está aberto para contribuições .