Sou um desses desenvolvedores que tem a mentalidade de que o código escrito deve ser auto-explicativo e lido como um livro. NO ENTANTO, ao desenvolver o código da biblioteca para outras pessoas, tento colocar o máximo de documentação possível nos arquivos de cabeçalho; o que levanta a questão: Os...
Gostaria de saber o que deve conter uma documentação de algoritmo? Não é possível localizar uma orientação adequada a seguir. Eu tenho em mente incluir resumo do algoritmo descrição do algoritmo fluxogramas pseudo códigos conjunto de dados de entrada de amostra (múltiplo) dados de saída testes de...
Parece-me que você não pode escrever uma especificação de software em inglês completamente livre de ambiguidades, simplesmente devido à natureza informal da linguagem natural - e, portanto, que uma especificação verdadeiramente inequívoca deve incluir código escrito em uma linguagem formalmente...
Uma parte essencial do Design Orientado a Domínio é o uso consistente de uma linguagem onipresente em todo o sistema - em conversas, código, esquema de banco de dados, interface do usuário, testes, etc. Estou envolvido em um projeto no qual já existe uma linguagem de domínio bem estabelecida,...
Sou um defensor do código devidamente documentado e estou ciente das possíveis desvantagens dele . Isso está fora do escopo desta questão. Eu gosto de seguir a regra de adicionar comentários XML para cada membro público, considerando o quanto eu gosto do IntelliSense no Visual Studio. Existe uma...
Fechado . Esta questão precisa ser mais focada . No momento, não está aceitando respostas. Deseja melhorar esta pergunta? Atualize a pergunta para que ela se concentre apenas em um problema editando esta postagem . Fechado há 5 anos . Atualmente, a...
Onde atualmente trabalho, a abordagem geral é - evitar a documentação o máximo possível Documente apenas se uma equipe diferente precisará apenas para esclarecimento, não me refiro à documentação do código - é o que fazemos, quero dizer toda a documentação que envolve o processo de design - se...
No momento, estamos usando métodos ágeis no meu projeto atual e temos montes de histórias como estas: Como assistente, quero pagar um reembolso a um cliente para que ele possa receber algum dinheiro quando solicitá-lo Como cliente, quero pagar por uma compra para poder receber meu item. O modo...
Sou um desenvolvedor amador e todos os meus programas até agora eram simples o suficiente para serem documentados dentro do código. Ao ler o código, ficou claro o que eu estava fazendo tal e tal ação (meu teste padrão foi examinar o código seis meses depois e entender tudo na primeira leitura - e...
Criamos uma biblioteca comercial e exemplos de código que estão sendo usados por desenvolvedores externos. Temos (fechado, disponível para usuários registrados) documentação que explica extensivamente como usar a biblioteca. Muitos dos desenvolvedores são usuários iniciantes, então muitos erros...
Eu costumava gostar de exigir comentários XML para documentação. Desde então, mudei de idéia por dois motivos principais: Como um bom código, os métodos devem ser auto-explicativos. Na prática, a maioria dos comentários XML são ruídos inúteis que não fornecem valor adicional. Muitas...
Documentei meu código doxygen, mas não quero o HTML padrão que ele fornece. Eu sei que posso personalizá-lo fornecendo CSS, cabeçalhos, rodapés personalizados etc. (como o GNOME faz), e como posso adicionar código PHP comum aos arquivos e pedir para que ele salve como .php, mas não é exatamente...
Quais informações você espera ver no README do github? Tudo deve estar no README? ie Introdução Instalação Versões Guia de usuario Implementação Teste Recursos Relacionados Ou você deve colocar certas coisas no README (Introdução, Instalação, Versões) e as outras informações são melhor...
Estou trabalhando em uma pequena biblioteca que fornece implementações de métricas básicas e bem conhecidas de strings. Principalmente para minha própria educação. Assim, o desenvolvimento acontece sempre que tenho um pouco de tempo livre. Por isso, automatizei a maioria dos processos para poder...
Então, você está corrigindo erros e encontrou um que poderia afetar outros módulos do produto de software. Seus dados não são suficientes para apoiar sua reivindicação sobre os efeitos da correção e você foi solicitado a criar um documento de análise de impacto. Existe um processo definido sobre...
Alguém tem sugestões para criar uma representação de fluxograma de uma interface da web no estilo REST? No interesse de fornecer documentação completa para os co-desenvolvedores, eu tenho trabalhado na modelagem da interface para modificar e gerar um recurso do produto: Esse sistema em...
Eu quero escrever Javadoc de maneira SECA. Mas o documento da Oracle sobre Javadoc diz que escreva a mesma coisa novamente no comentário do método de sobrecarga. Não posso evitar a
Ao revisar a implementação de uma função de outro programador para calcular a CDF de distribuição normal , sugeri substituir a implementação inteira pelas funções internas do Python ou usar o SciPy, uma biblioteca científica comum. Outro programador apontou que math.erfc()nem...
Estou prestes a sair de um projeto e, antes de partir, meu chefe me pediu para documentar o código (não o documentei muito bem). Não é grande coisa, o projeto não é terrivelmente complexo. Mas estou encontrando lugares em minha documentação onde gostaria de dizer: "Observe na linha XYZ que isso e...
Isso se refere a uma discussão em uma resposta e aos comentários desta pergunta: O que há com a aversão à documentação no setor? . A resposta alegou que "o código não pode mentir" e, portanto, deve ser o local de destino em vez da documentação. Vários comentários apontaram que "o código pode...