o valor da documentação de código

documentação de código é a coleção de imagens fáceis de entender e descrições escritas que explicam o que uma base de código faz e como ela pode ser usada.

pode ser simples comentários explicativos acima de funções e blocos, ou um manual completo de desenvolvimento, completo com estilo prescritivo dos-And-don’TS, visão geral de cada parte da aplicação, e abordagens para os tipos mais comuns de tarefas de codificação.

muitas vezes é melhor encontrar um meio feliz entre estes dois extremos quando você toma a decisão consciente de comentar o seu código e delinear as áreas gnarlier de uma base de código em linguagem simples.

por que documentar o seu código?

porquê dar-se ao trabalho de escrever sobre o seu código, em vez de apenas escrever o código? Não seria mais produtivo?

Mental Salvar Pontos

Documentação é como um mental save point para aqueles momentos quando você finalmente conseguir o que está acontecendo no final do dia e não quer perder o ímpeto. Código bem documentado irá garantir que quando você precisa mergulhar de volta amanhã de manhã (ou vários meses a partir de Agora), você não terá que levar tanto tempo para se atualizar.

o código documentado é reutilizado

a diferença entre uma biblioteca usada e uma biblioteca não utilizada geralmente se resume à sua documentação.

quem quer usar uma biblioteca de código aberto não documentada ou contribuir para um projecto não documentado? Quase ninguém.

na maioria dos casos, você prefere usar uma biblioteca menos poderosa que tem documentos. Por quê? Porque a documentação transmite outros pontos de informação sobre uma base de código. Os desenvolvedores acreditam que o projeto vale o tempo e a energia para escrever sobre ele em linguagem clara para que qualquer um que possa estar interessado possa rapidamente começar e aprender como ele funciona, e por que as decisões-chave foram tomadas.Encontrar um projecto novo, interessante e bem documentado na sua língua favorita pode ser muito emocionante e divertido. Vamos olhar para a alternativa extrema: ser obrigado a usar uma biblioteca de código não documentada e potencialmente contribuir para uma codebase aparentemente bizantina… parece muito doloroso, certo?Por que não documentou o seu próprio código?

document code is part of writing good code

A cornerstone of good code is maintainability, achieved through comprehensive, legible documentation.

existem várias formas de documentar o código:

• escolher bons nomes de variáveis e funções
• deixando breves comentários dentro do código para ajudar a dar o contexto para futuros leitores
• adicionar ilustrativas imagens, tais como a seqüência e diagramas de relacionamento de entidades
• fornecendo API do google docs, descrevendo cada classe, método, argumentos e valor de retorno
• usando uma linguagem de tipo estático, como o TypeScript (tipos de documentação)

Compare os dois exemplos

Vamos dizer que você está recebendo alguns dados a partir de uma API de back-end e “ingressing” ele -, convertendo-o em uma forma mais útil forma de um interface de utilizador. Aqui está a primeira de duas soluções possíveis.

// wdgt.jsexport const converter = (w) => { wdgtHdr = { name: w.nm, id: w.id, ts: w.lastTS } wdgtDtl = { dtlId: w.dtlId, dtlName: w.dtlNm, openTS: w.oTS, closeTS: w.cTS } wdgtRev = w.revs.map((r) => { const { note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = r const rr = { assocId: prsn1Id, assoc: `${prsn1Fn} ${prsn1Ln}`, amount: amt, note: note, revTS: cTS, } return rr } return { wdgtHdr, wdgtDtl, wdgtRev }}

o código acima tem o potencial de ser doloroso. Você pode ver pelo nome que este é algum tipo de conversor que toma w como seu param.

it looks like it returns a header, maybe details, and something called revs. De onde veio o revs? Claro que não há detalhes sobre os nomes das variáveis que chegam note, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS… ou há? rr diminutivo de returned rev? Quem sabe?Vejamos o segundo exemplo.

// widget_utils.ts// widgetConverter :: widgetRespDTO -> widgetexport const widgetConverter = (wResp: widgetRespDTO): Widget => { const widgetHeader: WidgetHeader = { name: wResp.nm, id: wResp.Id, ts: wResp.lastTS), // timestamp } const widgetDetail: WidgetDetail = { id: wResp.widgetId, name: wResp.dtlNm, openTS: wResp.oTS, // timestamp closeTS: wResp.cTS // timestamp } // is nested inside of WidgetRespDTO // .map -> const widgetRevisions: ReadonlyArray<WidgetRevision> = wResp.revs.map((wRevs: WidgetRevisionsRespDTO): WidgetRevision => { // how that other team names their variables...! const { cmt, prsn1Id, prsn1Ln, prsn1Fn, amt, cTS } = wRevs const comment: string = cmt const associateId: string = prsn1Id const associateName: string = `${prsn1Fn} ${prsn1Ln}` const amount: number = amt const revisionTS: number = cTS // unix timestamp, and "closeTS" fyi return { associateId, associateName, amount, comment, revisionTS, } } return { widgetHeader, widgetDetail, widgetRevisions, }}

que diferente! Esta função está em um arquivo util, então o arquivo principal já está menos confuso. Ele também está escrito em TypeScript em vez de JavaScript simples, então temos o benefício de definições de tipo para ajudar a nos guiar.

estamos convertendo widgetRespDTO s em widget s. Embora encurtado, temos pleno conhecimento do que é wResp. Estamos criando um widgetHeader, e um widgetDetail, que é fácil de ver. Nós também entendemos o que são oTS e cTS. Podemos dizer que WidgetRevisionsRespDTO s estão aninhados dentro de WidgetRespDTO.

alguém gentilmente renomeou as variáveis recebidas para que todos os que vêem este código saibam o que são. Finalmente, vemos um Widget deve ser composto do objeto retornado {widgetHeader, widgetDetail, widgetRevisions}, uma vez que deve corresponder ao tipo de retorno Widget especificado no topo.

qual o código que se sentiria melhor em utilizar?Prestações de maternidade

o código bem documentado beneficia muitas pessoas:

os programadores juniores

porque é em linguagem simples e fácil de entender, a documentação ajuda os programadores juniores e os novos membros da equipa a sentirem-se confiantes a saltar para uma base de dados. Isto evita a frustração e o abandono precoce de uma tarefa porque se torna demasiado complicado demasiado rapidamente.

também é útil para os desenvolvedores Júnior escrever sua própria documentação para que eles possam compartilhar seu código com os outros e para que eles possam obter uma melhor compreensão de seu código.

os programadores Seniores

ao tomar o tempo para documentar agora, os devs seniores gastam menos tempo a explicar o seu código a outros no futuro.

eles também podem escrever código mais complexo. A documentação em linguagem simples permite aos outros usá-la como uma caixa preta, sem ter que entender o funcionamento interno.

equipas & projectos de código aberto

as mudanças de pessoal podem trazer um tremendo abrandamento a um projecto. O código atualizado e bem documentado pode servir como Seguro contra tais atrasos e permitir que os membros restantes da equipe para dar um passo atrás, rever o código de alto nível e decidir sobre o melhor curso de ação avançando, e se necessário, a bordo novos funcionários.Quando documentar o código, deve resumi-lo. A fim de resumir corretamente, você deve ser capaz de compreendê-lo, segurando as diferentes partes em sua cabeça ao mesmo tempo. Escrever ou contribuir para a documentação é um atalho para realmente entender uma base de código, fazendo enormes contribuições, e sentindo-se como uma grande parte de uma grande equipe.

boa documentação pode secar a nossa experiência de codificação

como programador que provavelmente já ouviu falar do princípio de não se repetir como uma chave para escrever código limpo e conciso. Em vez de repetir o mesmo bloco de código várias vezes, escreva uma função que pode ser escrita uma vez e empregada em toda a sua aplicação.Da mesma forma, você e a sua equipa não devem ter problemas semelhantes e reinventar a roda sempre que tentarem resolvê-los. Por exemplo, você já ouviu um de seus colegas de trabalho ou se viu dizendo:

“Agh, Eu resolvi algo muito semelhante a isso, mas eu nunca me lembro como eu faço isso quando surge… Devia escrevê-lo algures, não?”

você então encontra-se digitalizando os mesmos tópicos de Overflow da pilha uma e outra vez.Salve – se a si e aos seus colegas de trabalho, seguindo o espírito do princípio seco e escrevendo um documento que pode utilizar sempre que a questão surgir! Isso vai ajudar você e outros em sua equipe a economizar tempo, e ser mais eficaz na escrita código mais simples, mais gerenciável e mais eficiente.

como é que a documentação do código, ou a sua falta, o afectou?