Pausa para café #79. 10 erros que os desenvolvedores Java cometem que os impedem de alcançar o sucesso. Guia do desenvolvedor para escrever comentários de código significativos

10 erros que os desenvolvedores Java cometem que impedem seu sucesso

Fonte: Dev.to Com base na minha experiência, compilei uma lista de 10 erros que os desenvolvedores cometem e que os impedem de alcançar o sucesso:

1. Não escreva testes unitários

Os desenvolvedores que não escrevem testes unitários cometem mais erros em seu código. Isso leva à instabilidade do produto e à insatisfação do cliente.

2. Eles não verificam o código manualmente

Mesmo que você cubra completamente seu código com testes de unidade, ainda há uma chance de você ter perdido alguma coisa. É sempre recomendável testar manualmente seu código antes de enviá-lo para revisão. Desta forma você pode detectar erros na fase de desenvolvimento.

3. Eles pensam: “Isso nunca vai acontecer”.

Os desenvolvedores muitas vezes cometem erros ao escrever um novo código, pensando que determinados cenários nunca acontecerão. No final, acontece que eles estão errados. Lide com todos os cenários onde o código pode ser executado. Métodos de programação defensiva irão ajudá-lo com isso.

4. Não receba feedback

Solicite regularmente feedback de outros desenvolvedores e usuários. Compartilhe sua opinião com seus colegas.

5. Eles não verificam a funcionalidade do código.

Freqüentemente, os desenvolvedores escrevem seu código, mas não verificam sua funcionalidade. Como resultado, quando o código chega à produção, ele cria vários problemas.

6. Escreva um código processual longo

É muito fácil escrever métodos longos com muita lógica. Ao fazer isso, os programadores implementam a mesma lógica em muitos lugares. Projetos com um número significativo de métodos pequenos têm uma reutilização de código muito melhor e são muito mais fáceis de manter.

7. Eles não conhecem as ferramentas

As ferramentas são uma extensão das suas mãos. Quanto melhor você os conhecer, mais produtivo você será. Você deve estar bem familiarizado com o IDE que está usando. Aprenda comandos rápidos, sempre há comandos que vão te ajudar a ser ainda mais produtivo. No IntelliJ IDEA são Sonar Lint, Spot bugs e Code Metrics.

8. Ignore problemas no código

Os desenvolvedores que trabalham nos produtos de maior sucesso mudam constantemente o código. Não tenha medo de refatorar seu código. Se o seu código for testado em unidade, há pouca chance de regressão. Os desenvolvedores geralmente ignoram códigos problemáticos. Como desenvolvedor, você é responsável por manter o aplicativo em boas condições. Por esse motivo, corrija todos os problemas que encontrar.

9. Eles codificam sem perceber as consequências.

Os desenvolvedores NUNCA devem fazer alterações no código e lançá-lo em produção sem compreender as consequências. O código pode produzir resultados corretos para os valores de teste fornecidos. No entanto, pode haver cenários em que isto possa levar a resultados imprevisíveis e criar problemas graves. A codificação “imprevisível” geralmente acontece quando os desenvolvedores usam funções de bibliotecas que eles não entendem totalmente. Isso também pode acontecer quando um desenvolvedor resolve um problema sem entender a solução.

10. Não peça ajuda

Os desenvolvedores não são pessoas muito sociáveis. Eles gostam de resolver problemas sozinhos. Mas a era em que o próprio desenvolvedor cria um produto do início ao fim acabou. O desenvolvimento de software é uma atividade de equipe. Quando você encontrar um problema durante a programação, tente resolvê-lo sozinho. Mas não perca muito tempo se não conseguir encontrar uma solução. Há uma grande chance de que alguns de seus colegas já tenham encontrado o mesmo problema e conheçam a solução. Isso economizará tempo e aumentará a produtividade.

Guia do desenvolvedor para escrever comentários de código significativos

Fonte: Stepsize Na maioria dos casos, você não é o único trabalhando no mesmo projeto ou base de código. Isso significa que outras pessoas devem entender seu código. Isso também se aplica a comentários de código. Os desenvolvedores costumam escrever comentários “rápidos e sujos” sem muito contexto, deixando seus colegas confusos sobre o que o autor estava tentando dizer. Esta é uma má prática e cria mais confusão do que clareza. Ter comentários de código claros ajuda outros desenvolvedores. Um comentário de código que descreve uma função, sua lógica, entrada e saída acelera o processo de aprendizagem para outros desenvolvedores. Por outro lado, os comentários do código nos levam à pergunta: vale a pena escrevê-los? Um grupo significativo de desenvolvedores se opõe à escrita de comentários de código. A razão é que o código, na opinião deles, é autoexplicativo. Se outro desenvolvedor não conseguir entender o propósito do seu código olhando para ele, então é um código incorreto. Talvez isso seja verdade. Mas pense no pequeno esforço necessário para comentar o código e nos benefícios potenciais que ele traz. Os comentários do código são importantes para acelerar o processo de integração de qualquer desenvolvedor, especialmente os juniores. Vejamos os diferentes tipos de comentários de código.

1. Comentários sobre a documentação.

O principal objetivo de tais comentários é esclarecer rapidamente a finalidade de um arquivo ou componente. Em vez de ler todo o código de um componente para entender o que ele faz, você pode adicionar um comentário de código no topo do arquivo `index`. Isso ajudará a explicar o que esse componente faz. Não sou muito fã desse tipo de comentário porque atrapalha um pouco o código. Acho que esses tipos de comentários sobre arquitetura deveriam estar em sua documentação interna, onde você pode manter e discutir centralmente a arquitetura do seu projeto. No entanto, os projetos de código aberto realmente precisam deles.

2. Comentários sobre funções.

Este é o tipo de comentário mais útil. Eles descrevem a finalidade da função, seus parâmetros e sua saída.

/**
 * @desc Creates a welcome message
 */
function sayHello(name) {
    return `Hello ${name}`;
}

3. Comentários lógicos.

Estes são comentários dentro de funções para esclarecer caminhos de código complexos. Como você deve ter adivinhado, a presença de tais comentários indica que seu código é muito complexo. Além disso, os comentários lógicos geralmente contêm muitas informações detalhadas. O nível de detalhe criará mais caos e reduzirá a legibilidade do seu código. Aqui está um exemplo de comentário de código excessivamente detalhado.

let date = new Date(); // store today's date to calculate the elapsed time

Comentários de código: 4 práticas recomendadas para comentários

1. Use anotações ou tags de código

Muitas linguagens de programação definem padrões para comentários de código. Java usa Javadoc , enquanto JavaScript usa o sistema de comentários de código JSDoc , que é suportado por muitas ferramentas de documentação. Para funções você deve incluir as seguintes tags de código:

• @desc – descrição da sua função
• @param – todos os parâmetros de entrada que a função aceita. Certifique-se de especificar os tipos de entrada.
• @returns – saída retornada. Certifique-se de especificar o tipo de saída.
• @throws é o tipo de erro que a função pode gerar.
• @example - um ou mais exemplos que mostram a entrada e a saída esperada.

Aqui está um exemplo de código Lodash para a função chunk .

/**
 * Creates an array of elements split into groups the length of `size`.
 * If `array` can't be split evenly, the final chunk will be the remaining
 * elements.
 *
 * @since 3.0.0
 * @category Array
 * @param {Array} array The array to process.
 * @param {number} [size=1] The length of each chunk
 * @returns {Array} Returns the new array of chunks.
 * @example
 *
 * chunk(['a', 'b', 'c', 'd'], 2)
 * // => [['a', 'b'], ['c', 'd']]
 *
 * chunk(['a', 'b', 'c', 'd'], 3)
 * // => [['a', 'b', 'c'], ['d']]
 */
function chunk(array, size = 1) {
  // logic
}

2. Explique o motivo de suas ações

Muitos desenvolvedores usam comentários para descrever o que seu código faz. Ao fazer isso, inclua por que você criou um recurso ou componente específico. Essa informação é chamada de contexto. O contexto é importante para fornecer aos desenvolvedores mais informações sobre as decisões de design por trás de um recurso ou componente. O contexto é fundamental quando outros desenvolvedores desejam fazer alterações em seu recurso ou componente. Abaixo você pode ver um mau exemplo de comentário de código sem contexto.

/**
 * Sets the label property of a new form.
 *
 * @param label text for label of form
 */
function setFormLabel(label) {
    // logic
}

3. Não crie links para outros documentos ou comentários

Não é recomendado vincular outros comentários de código ou documentos internos que expliquem um recurso ou componente.

/**
 * Sets the label property of a new form.
 *
 * @see {@link https://myinternaldocument.com}
 */
function setFormLabel(label) {
    // logic
}

4. Escreva comentários durante a codificação

Isso pode parecer óbvio, mas muitos desenvolvedores (inclusive eu) negligenciam essa regra. Deixar comentários para mais tarde é ruim porque você pode esquecer parte da lógica que escreveu, o que levará a comentários de código de qualidade inferior. Isso é especialmente verdadeiro se você estiver trabalhando na mesma solicitação pull por vários dias. É melhor escrever comentários quando você terminar um recurso ou módulo. Lembre-se de manter os comentários do código tão breves quanto possível. Você não precisa gastar mais tempo escrevendo comentários do que escrevendo o próprio código.