Documentação do código primeiro? [fechadas]

11

Alguém já tentou criar uma documentação completa do código primeiro, antes de realmente escrever o código? Eu estava pensando sobre isso mais cedo, porque pensei que ajudaria a escrever uma interface concreta e garantiria que seu design inicial não fosse pavimentado, fazendo você pensar sobre como as classes interagem. isso é uma boa ideia? Alguém já tentou? Ell

documentation ell
fonte
2
Sim. É uma boa ideia. Pessoas fazem isso o tempo todo. O que mais você quer saber?
27511 S.Lott
9
Esta é uma pergunta subjetiva. Alguém já fez isso pelo menos uma parte do tempo, então a resposta é sim. Pessoalmente, prefiro simplesmente entrar e fazer um protótipo primeiro, pois inevitavelmente redescobrir um design melhor cerca de 5 vezes no processo. Ao abordar algo complexo, primeiro coço algo em um pedaço de papel. Se for trivial, então tendem a pular direto. O StyleCop me ajuda a preencher as lacunas mais tarde.
Job
2
É uma ótima idéia, caso contrário, você terá recursos não documentados.
ChrisW
8
@ S.Lott o simples fato de que ele está fazendo a pergunta implica que ele está procurando mais informações, pois tenho certeza de que você estava ciente. Mas parece que você prefere fazer comentários maliciosos sobre falhas de outras pessoas.
19411 Kenneth
2
Seria ainda melhor se você escrevesse testes de aceitação e usasse o TDD para realizar esses testes;).
Martin Blore 17/03

Respostas:

5

Sim.

Isso faz você pensar sobre o que exatamente seu código deve fazer. A idéia é que você possa começar com qualquer parte do código e saber exatamente o que precisa ser feito para concluir esse módulo.

Também é mais fácil consertar algo na prancheta do que no IDE.

Maxpm
fonte
12
Mais fácil de corrigir, sim. Mais fácil perceber, raramente. Os projetos quase sempre ficam bem até você tentar implementá-los.
CaffGeek 17/03
@ Chad Isso é verdade. Eu editei minha resposta para refletir isso.
Maxpm 17/03/11
4
Discordo. Criar a documentação completa primeiro é muito pior do que apenas a documentação suficiente para saber para onde ir. Mudança acontece. Não há como saber se você está indo na direção certa e, no momento em que descobre, já está muito atrasado. Siga o que funciona, melhore e corrija-o à medida que avança, deixe o código ser a documentação mais atualizada.
Zachary Scott
4
Obviamente, assim que você altera seu código para corrigir um bug ou atender a um novo requisito, sua documentação fica desatualizada. A documentação como testes executáveis é o caminho a seguir!
Johnsyweb
Elabore idéias (esboço / esboço) de antemão, sim, mas não crie documentação. A menos que você prefira desperdiçar muito esforço, porque estará jogando muito fora do esforço inicial, pois o design é aplicado à aplicação prática. Além disso, apenas classes / métodos públicos ou internos devem ser totalmente documentados (incluindo descrição completa e parâmetros). Coisas locais privadas devem ter uma linha que descreva o que fazem para referência futura, mas qualquer coisa mais é um desperdício, porque elas serão inevitavelmente ignoradas durante a fase de geração da documentação.
Evan Plaice
10

Existem duas maneiras de pensar sobre isso:

1) Documentação como nos documentos do Word, Wiki, etc. Por definição, você não pode ter uma documentação de código completa porque não possui um código para documentar. Você pode tentar documentar design de alto nível, suposições, interfaces e contratos primeiro.

2) Documentação como testes executáveis. Existe uma escola de pensamento que afirma que os testes de unidade executável são a melhor documentação. Essa escola de pensamento também defende esse tipo de documentação antes de escrever o código (TDD). Ao mesmo tempo, você não escreve todos os testes para todo o sistema desde o início. Você divide-os primeiro por casos de uso e depois faz testes e códigos por caso de uso.

Yuriy Zubarev
fonte
2
+1 para TDD. Absolutamente uma opção melhor do que documentar, depois ter que alterar quantidades significativas de documentação se o código for alterado.
Ethel Evans
Também +1 para documentação na forma de TDD.
sevenseacat
você PODE ter a documentação completa do produto antes que ele exista. Eu já fiz isso, trabalhei em projetos onde era um requisito. Você não terá capturas de tela, mas poderá ter todo o resto (incluindo diagramas do Visio representando a localização dos elementos na tela).
jwenting
@jwenting Eu também tenho e era uma coleção de diagramas, além de mais de 200 páginas de documentos do Word. Não apenas foi um desperdício de tempo completo, mas foram necessários 2 meses para produzir e uma quantidade significativa de tempo de nossos PMs foi atualizada constantemente à medida que o design evoluía para o produto final. Na verdade, provavelmente teria sido muito mais rápido com modelos gráficos usando o Balsalmiq. Na próxima vez em que trabalhar em um projeto em que isso seja um requisito, enfatizarei que outra pessoa deve ser designada para gerenciá-lo em tempo integral, porque esse é o esforço necessário para manter.
Evan Plaice
+1 TDD para provas básicas de componentes individuais e diagramas para suposições gerais do projeto (ênfase na suposição porque o design real deve ser escrito como a melhor aplicação prática, não como uma implementação 1-1 do diagrama, eles são chamados de suposições por uma razão ) A documentação completa do software de todas as classes / métodos / propriedades públicas / internas vem por último através de um gerador de documentação (todas as propriedades / devoluções / observações devem ser preenchidas primeiro) e todo o material privado / local recebe uma lista para descrever o que eles fazem para referência futura (privado / local é ignorado pelo gerador).
Evan Plaice
7

Começando com a documentação é o modelo clássico em cascata e possui todas as armadilhas associadas a esse modelo. Em termos gerais, quanto mais você documenta, mais precisa atualizar quando os requisitos mudam. Um benefício de começar com a documentação do usuário é que você pode obter feedback (e, portanto, alterações) antes. Mas a experiência mostra que a maioria das pessoas é ruim em mapear mentalmente a documentação para as ações. Por isso, usamos protótipos, que permitem que as pessoas usem o software e dê feedback dessa maneira.

Uma variação da "documentação primeiro" é a programação alfabetizada . Comece escrevendo uma descrição do que o programa fará da perspectiva dos programadores. Continue ajustando isso até compilar. Voila, um programa alfabetizado.


fonte
Exatamente! Mudança acontece. A documentação apodrece. Código é a forma mais verdadeira de documentação.
Zachary Scott
3

Pessoalmente, acho melhor usar diagramas (como UML) para fazer modelagem simples para mostrar o fluxo das coisas. Isso é muito mais rápido do que documentar as coisas em palavras e, se bem feito, pode ser igualmente descritivo. Eu hesitaria em fazer a Documentação Completa, porque, pessoalmente, nunca tive um projeto em que trabalhei que não mudou ao longo da programação.

EDIT: No entanto, alguma documentação deve ser feita à medida que você avança. Isso facilita a documentação completa posteriormente.

Kenneth
fonte
3

Joshua Bloch discute esse ponto em sua entrevista para o livro "Coders at Work".

Ao contrário de visões mais ortodoxas e acadêmicas, ele aconselha algo que melhore seus pensamentos (talvez você já tenha lido isso lá?): Antes de escrever a documentação, você precisa entender o que deseja do sistema e obter uma visão mais "real". " sentindo-me. Para esse propósito, ele projetaria parte das interfaces e algum código do cliente que as utiliza.

O mais importante é saber o que você está tentando criar: que problema você está tentando resolver. A importância da análise de requisitos não pode ser exagerada. Há pessoas que pensam: “Sim, análise de requisitos; você vai ao seu cliente e diz: 'O que você precisa?' Ele diz a você e pronto.

Nada poderia estar mais longe da verdade. Não é apenas uma negociação, mas um processo de entendimento. Muitos clientes não vão lhe dizer um problema; eles lhe dirão uma solução. Um cliente pode dizer, por exemplo, “preciso que você adicione suporte para os 17 atributos a seguir neste sistema. Então você tem que perguntar: 'Por quê? O que você vai fazer com o sistema? Como você espera que isso evolua? '”E assim por diante. Você vai e volta até descobrir o que todo o cliente realmente precisa que o software faça. Estes são os casos de uso.

Criar um bom conjunto de casos de uso é a coisa mais importante que você pode fazer neste estágio. Depois de ter isso, você terá um benchmark com o qual poderá medir qualquer solução possível. Tudo bem se você gastar muito tempo aproximando-o razoavelmente da direita, porque se você errar, você já está morto. O restante do processo será um exercício de futilidade.

A pior coisa que você pode fazer - e eu já vi isso acontecer - é colocar um monte de caras espertos em uma sala para trabalhar por seis meses e escrever uma especificação de sistema de 247 páginas antes que eles realmente entendam o que é. tentando construir. Porque, após seis meses, eles terão um sistema especificado com muita precisão que pode muito bem ser inútil. E eles costumam dizer: "Investimos tanto nas especificações que precisamos construí-las". Então eles constroem o sistema inútil e ele nunca é usado. E isso é horrível. Se você não tem casos de uso, cria a coisa e tenta fazer algo muito simples e percebe que: “Oh meu Deus, fazer algo muito simples como pegar um documento XML e imprimi-lo requer páginas e páginas de clichê código." E isso é uma coisa horrível.

- Joshua Bloch, de uma entrevista em " Coders at Work: Reflections on the Craft of Programming ", de Peter Seibel

Se você já está pensando nesse sentido, seria bom se você pudesse ler o livro e ler a entrevista inteira. Como eu disse, ele é sempre muito esclarecedor.

DPM
fonte
Este é um bom conselho, mas uma boa documentação inclui o uso da API.
Frank Hileman
Para o registro, enquanto eu aprecio a edição, acho que essa citação pode não ter sido a que eu estava pensando. Parece tangencialmente relacionado e com um nível mais alto ou relacionado à fase de requisitos. Acho que ele disse que antes de escrever a documentação, ele começaria a codificar, escrevendo o código do cliente que usaria a interface para ter uma idéia aproximada da interface correta e que (esta é a parte contra-intuitiva na minha opinião) que deve vir primeiro, antes de escrever qualquer documento de design de baixo nível. Claro que é minha culpa por não ter encontrado a citação quando escrevi esta resposta.
DPM
1

Algumas pessoas ainda vão além e afirmam que uma empresa deve trabalhar completamente para trás, então

  1. Escreva o comunicado de imprensa
  2. Escreva uma FAQ
  3. Definir a experiência do cliente
  4. Escreva o manual do usuário
  5. Iniciar a programação

Consulte http://www.allthingsdistributed.com/2006/11/working_backwards.html

asmaier
fonte
1

Escrever a documentação completa do código primeiro é provavelmente um exagero e uma reminiscência da metodologia em cascata. No entanto, descobri que uma abordagem mais pragmática está escrevendo o README primeiro. Aqui está o porquê:

O README não documenta todos os detalhes do seu projeto. Em vez disso, normalmente contém as seguintes informações:

  1. Descrição : breve "discurso de vendas". Diga ao leitor por que eles devem continuar lendo.
  2. Exemplos rápidos : snippets de código curto ou capturas de tela para dar suporte à descrição.
  3. Início rápido : como começar, instruções de instalação e mais exemplos.
  4. Mais documentação : links para a documentação completa e mais informações.
  5. Organização do projeto : quem são os autores, como contribuir, como arquivar bugs.
  6. Avisos legais : licença, direitos autorais e outros detalhes legais.

Escrever o "discurso de vendas" antecipadamente me obriga a esclarecer por que esse projeto deveria existir e por que os desenvolvedores deveriam usá-lo. O simples ato de escrever frases completas para descrever o projeto geralmente o altera para melhor: você o entende melhor, desenvolve novas idéias e descobre possíveis problemas. Também é uma ótima ferramenta de priorização: qualquer coisa no "discurso de vendas" é essencial!

Os "exemplos rápidos" e o "guia de início rápido" me forçam a pensar nos principais casos de uso da perspectiva do usuário. Descobri que fazer isso antes de escrever qualquer código - antes de se atolar nos detalhes da implementação e nos prazos apertados - leva a APIs e designs muito mais limpos. Lembre-se: os programas devem ser escritos para as pessoas lerem e, incidentalmente, para as máquinas executarem ( SICP ).

Em "documentação adicional", crio um esboço das peças que precisarão de documentação detalhada, a ser feita posteriormente. "Organização do projeto" permite-me descobrir quem trabalhará no projeto e nas práticas de codificação. "Avisos legais" ... bem, também podem tirá-los do caminho.

Depois de ter este README básico em vigor, você terá um documento útil para discussão, revisões de design, divisão do trabalho e planejamento do projeto. Enquanto você trabalha no projeto, verifique frequentemente o README para garantir que você ainda esteja no caminho certo. Além disso, atualizar gradualmente o README e a "documentação adicional" à medida que avança significa que toda a sua documentação será concluída quando o código for concluído, o que é uma experiência muito mais agradável do que ter que se apressar em documentar tudo no último minuto.

Para mais informações, confira o seguinte:

  1. Desenvolvimento orientado por leia-me
  2. O código mais importante não é código
  3. Você é o que você documenta
Yevgeniy Brikman
fonte
0

Por que você não gostaria de pensar em como as aulas interagem? Por que isso é ruim? Na verdade, penso nas interações antes mesmo de saber quais são as aulas. Dessa forma, as classes se identificam.

Dunk
fonte
0

Você deve ter uma idéia do que planeja fazer antes de escrever o código. A questão sempre é como você mantém o que codificou em sincronia com o que escreveu? Alguns dizem que não tente, outros dizem que esqueça os documentos iniciais e mantenha os comentários. Claro que o código é sempre a fonte canônica. A questão passa a ser se vale a pena documentar o que o código faz para quem chega mais tarde ou usa o código. Qualquer um pode descobrir o que uma função faz. O trabalho do escritor é ajudar alguém a entender em 5 minutos o que alguém pode descobrir em uma hora. Adicione os deltas e determine seu caminho.

SnoopDougieDoug
fonte