Liberando a produtividade do desenvolvedor: Aprenda sobre código “em nível de documento”?

Uma piada duradoura na Internet:

As quatro coisas que os programadores mais odeiam:

escrever notas

escrever documento

Outros não escrevem comentários

Outros não escrevem documentos

Hoje começaremos com documentos que os desenvolvedores “não suportam e dos quais não conseguem se livrar”.

1. A importância da documentação

A documentação de alta qualidade é uma ferramenta eficaz para registrar e comunicar informações, ajudando as pessoas a compreender e cumprir normas, políticas e procedimentos. Eles também servem como referência e evidência para apoiar a tomada de decisões e a resolução de problemas. Através de registros escritos, as pessoas podem preservar e compartilhar conhecimento por longos períodos de tempo. Além disso, uma boa documentação melhora a eficiência do trabalho e reduz mal-entendidos e erros. Em resumo, a documentação desempenha um papel importante na vida pessoal e no trabalho e é crucial para a sustentabilidade de uma organização.

Documentação de alta qualidade traz muitos benefícios para uma organização ou equipe.

Primeiro, a documentação pode facilitar a compreensão do código e da API, reduzindo a chance de erros.

Em segundo lugar, a documentação permite que os membros da equipe se concentrem mais em seus objetivos e resolvam os problemas rapidamente.

Além disso, a documentação também facilita algumas tarefas manuais.

Além disso, se novos membros ingressarem, a documentação pode ajudá-los a se integrarem à equipe mais rapidamente.

Escrever documentação tem um sério atraso de receita. Ao contrário dos testes, a execução de um caso de teste pode dizer imediatamente se está correto ou não, e seu valor é refletido imediatamente.
Ao escrever um documento, sua importância ficará evidente com o tempo. Você só pode escrever uma vez, mas será lido muitas, centenas ou até milhares de vezes.

Um excelente documento pode responder às seguintes perguntas no futuro:
• Por que tal decisão foi tomada naquela época?
• Por que o código é implementado desta forma?
• Que conceitos estão sendo incorporados neste projeto?
•...
Escrever documentação também traz enormes benefícios para o próprio autor:
• Ajudar você a padronizar o design da API: Escrever documentação é um processo de revisão da API. Escrever documentação pode fazer você pensar se o design da API é razoável e abrangente. Se você não consegue descrever a API com precisão em palavras, o design atual da API não é razoável.
• A documentação também é outra forma de apresentar o código: por exemplo, se você vir o código que escreveu novamente dois anos depois, desde que haja comentários e documentação, você poderá entendê-lo rapidamente.
• Melhorar o profissionalismo do código: Todos temos a sensação de que, desde que a API tenha documentação completa, ela é uma API bem projetada. Embora esse sentimento não seja totalmente correto, os dois são de fato inseparáveis. Aos olhos de muitas pessoas, a integridade da documentação também se tornou um indicador do profissionalismo de um produto.
• Evite interrupções desnecessárias com perguntas repetidas: Algumas perguntas podem ser registradas diretamente no documento, para que quando alguém vier perguntar, você possa permitir que ele visualize o documento diretamente, sem precisar explicá-lo novamente. .

2. Por que a maioria das pessoas não gosta de escrever documentos

Por que muitas pessoas não desenvolveram o hábito de escrever documentos? Afinal, a documentação se torna muito importante depois de muito tempo resolvido o problema.

Além das razões do atraso na receita documental mencionadas anteriormente, existem também os seguintes fatores:

•Muitos engenheiros estão acostumados a separar codificação e escrita, não apenas em seu trabalho, mas também por pensarem que são duas tarefas completamente não relacionadas, o que leva muitas pessoas a se concentrarem mais no código e ignorarem a importância da documentação.

•Muitos engenheiros também pensam que não são bons em escrever, então simplesmente optam por não escrever. No entanto, esta é apenas uma desculpa preguiçosa. Na verdade, escrever documentos não requer retórica deslumbrante ou linguagem vívida, basta explicar o problema com clareza.

•Às vezes, a incapacidade de usar ferramentas também terá impacto na redação de documentos. Sem uma ferramenta de escrita de qualidade que integre a escrita de documentos ao fluxo de trabalho de desenvolvimento, a carga de escrita aumenta.

•A maioria das pessoas pensa que escrever documentos é outro fardo de trabalho. Não tenho mais tempo para escrever código, muito menos para escrever documentação! Na verdade, este é um conceito errado. Embora escrever documentação possa exigir algum investimento inicial, pode reduzir significativamente os custos posteriores de manutenção do código. Acredito que todos possam entender o princípio de afiar a faca antes de cortar madeira.

3. Ferramentas de IA para ajudar

Se existe uma ferramenta de programação de IA que pode gerar código "em nível de documento", ela pode resolver o grande problema da grande maioria dos desenvolvedores que não sabem ou não querem escrever comentários e documentos?

Como uma parte importante do robô de software SoFlu da Feisuan, o gerador FuncGPT AI suporta a criação de todos os tipos de funções . O gerador FuncGPT AI usa linguagem natural para descrever os requisitos de função Java e gera códigos de função Java de alta qualidade e altamente legíveis em tempo real. O código gerado pode ser copiado diretamente para o IDEA ou importado para a biblioteca de funções da ferramenta de desenvolvimento totalmente automática Java com um clique.

FuncGPT (Functions) pode muito bem resolver os seguintes problemas de código:

1. Especificações de código: Gere códigos de função que cumpram a sintaxe Java e as especificações de código. O código gerado será mais fácil de ler e entender.

2. Reutilização de código: O código de função gerado tenderá a usar as melhores práticas reutilizáveis. Pode reduzir o código redundante e melhorar a capacidade de manutenção do código.

3. Comentários de código: O código gerado conterá comentários de código claros para ajudar os engenheiros de desenvolvimento a compreender o propósito e a entrada e saída da função. Bons comentários são muito importantes para manutenção posterior.

4. Estrutura de código : O código gerado tenderá a usar uma boa estrutura de código e evitar funções excessivamente longas e aninhamento excessivo. Isso ajuda a melhorar a legibilidade e a manutenção do código.

5. Reduza significativamente o trabalho de depuração de código: o código gerado passou por treinamento conjunto em grande escala e pode gerar código mais preciso e estável, reduzindo assim o trabalho de depuração causado por erros de código.

Tomemos como exemplo o uso de funções Java no sistema de gerenciamento de tarefas para implementar a função de cálculo do tempo restante de uma tarefa:

// Nome da classe: DateUtils

// Nome da função: calcularDateDifference

// Função: Calcula o número de dias de diferença entre duas datas

// Pacote de dependência POM :

// <dependência>

// <groupId>joda-time</groupId>

// <artifactId>joda-time</artifactId>

// <versão>2.10.10</versão>

// </dependency>

importar org.joda.time.DateTime;

importar org.joda.time.Days;

classe pública DateUtils {

    /**

     * Calcule o número de dias de diferença entre duas datas

     * @param startTime horário de início

     * @param endTime horário de término

     * @returnA diferença na string de dias

     */

    public static String calculaDateDifference(DateTime startTime, DateTime endTime, String format) {

        Days days = Days.daysBetween(startTime, endTime); // Use Joda-Time para calcular o número de dias de diferença

        int diferença = dias.getDays();

        Resultado da sequência;

        mudar (formato) {

            caso " dia":

                resultado = diferença + "天";

                quebrar;

            caso " quando":

                resultado = diferença * 24 + " hora";

                quebrar;

            caso " ponto":

                resultado = diferença * 24 * 60 + " minutos";

                quebrar;

            padrão:

                throw new IllegalArgumentException("Formato inválido"); // Se o formato for ilegal, lança uma exceção

        }

        resultado de retorno;

    }

}

// exemplo de função

// Exemplo de cálculo do número de dias de diferença entre duas datas

// Parâmetros de entrada: startTime, hora de início, o tipo é DateTime; endTime, hora de término, o tipo é DateTime; formato, caractere de formatação, o tipo é String

// Parâmetros de saída: resultado, uma sequência de dias de diferença

// exemplo de chamada:

// DateTime startTime = new DateTime(2022, 1, 1, 0, 0); // Cria um objeto de hora de início

// DateTime endTime = new DateTime(2022, 1, 5, 0, 0); // Cria objeto de horário de término

// String result = DateUtils.calculateDateDifference(startTime, endTime, "天");

//System.out.println(resultado);

// Resultado de saída: por exemplo, calcule a diferença do número de dias entre 1º de janeiro de 2022 e 5 de janeiro de 2022: 4

// O resultado da saída é: 4 dias

Não é difícil encontrar através da análise:

1. Anotação : Há uma anotação XML acima do código, indicando que esta classe requer a versão 2.10.10 da biblioteca joda-time. Isso é muito importante para entender as dependências do código e do ambiente em execução.

2. Legibilidade : A nomenclatura do nome da função é clara e descritiva, o que indica a função principal da função. Os nomes dos parâmetros também são claros, facilitando a compreensão do que cada parâmetro faz. Cada bloco de código (como instruções de importação e corpos de funções) usa recuo e espaços em branco apropriados para facilitar a leitura do código.

3. Qualidade do código :

É uma boa prática usar o método Days.daysBetween para calcular a diferença em dias entre duas datas porque evita problemas que podem surgir ao fazer cálculos de diferença de horário diretamente (como horário de verão, fusos horários, etc. ) .
A estrutura switch-case é usada para processar solicitações em diferentes formatos, que podem atender com flexibilidade a diferentes necessidades. Para entrada de formato inválido, o método lança um IllegalArgumentException , que indica o tratamento da exceção.
Nomes de variáveis e nomes de métodos razoáveis são usados para tornar o código fácil de entender e manter.
Comentários razoáveis são usados para explicar a função do código e a função dos parâmetros.
Não há números mágicos ou valores codificados usados no código; em vez disso, constantes ou variáveis apropriadas são usadas.
O tipo de parâmetro de entrada é DateTime , o que torna a função muito versátil e pode aceitar vários formatos de hora.
O tipo de retorno é String , o que torna a saída da função boa legibilidade e exibição.

Se você também deseja experimentar a experiência de desenvolvimento eficiente e de alta qualidade proporcionada pelo FuncGPT, baixe e use-o gratuitamente: https://c.suo.nz/74QvS

Liberando a produtividade do desenvolvedor: Aprenda sobre código “em nível de documento”?

Acho que você gosta