A documentação do software é um texto escrito que acompanha o software do computador. Explica como o software opera, como instalá-lo, como usá-lo e outros recursos para obter ajuda.
Muitas pessoas afirmam que "os comentários devem explicar 'por que', mas não 'como'". Outros dizem que "o código deve ser auto-documentado" e os comentários devem ser escassos. Robert C. Martin afirma que (reformulado com minhas próprias palavras) frequentemente "os comentários são desculpas por...
Pediram-me especificamente para dar linha por linha (ou conforme apropriado - por exemplo, imagem por imagem, etc.) explicação ou comentário que meu chefe deseja poder ler e seguir. Como ele não é um programador, ele não pode seguir o código, por isso deseja que tudo seja traduzido para o...
O padrão RFC 2606 reserva os nomes de domínio exemplo.org , exemplo.net e exemplo.com com a finalidade de serem usados como exemplos na documentação. Qual é o equivalente a um número de telefone (incluindo o código do país) que pode ser usado como exemplo, por exemplo, para dar aos usuários um...
Suponha que eu esteja desenvolvendo um projeto relativamente grande. Eu já documentei todas as minhas classes e funções com o Doxygen, no entanto, tive uma ideia de colocar "notas do programador" em cada arquivo de código-fonte. A idéia por trás disso é explicar em termos leigos como uma classe...
Durante uma reunião sobre a reversão de um SDK de terceiros da versão mais recente, notou-se que nossos desenvolvedores já sinalizaram no histórico de confirmação que a versão mais recente não deveria ser usada. Alguns desenvolvedores argumentaram que essa era uma prática ruim e, em vez disso,...
Estou trabalhando em um projeto bastante grande e tive a tarefa de fazer algumas traduções para ele. Havia toneladas de etiquetas que não foram traduzidas e, enquanto eu vasculhava o código, encontrei esse pequeno pedaço de código //TODO translations Isso me fez pensar sobre o sentido desses...
Eu escrevi o seguinte código: if (boutique == null) { boutique = new Boutique(); boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
Primeiro de tudo, nesta pergunta, eu gostaria de ficar longe da polêmica sobre se o comentário do código fonte é bom ou ruim. Estou apenas tentando entender mais claramente o que as pessoas querem dizer quando falam sobre comentários que dizem por que, o que ou como. Muitas vezes, vemos diretrizes...
Eu estava trabalhando em um projeto há três meses e, de repente, outro projeto urgente apareceu e me pediram para mudar minha atenção. A partir de amanhã, voltarei ao projeto antigo. Percebo que não me lembro exatamente do que estava fazendo. Não sei por onde começar. Como posso documentar um...
Estou planejando deixar meu emprego atual porque estamos bloqueados no uso do Blub , com uma estrutura corporativa do Blub e um servidor da Web no nível do Blub, em hospedagem compartilhada medíocre. Meus colegas de trabalho são amigáveis e meu chefe é um proprietário médio de empresa de pequeno...
Entendo a importância do código bem documentado. Mas também entendo a importância do código de auto-documentação . Quanto mais fácil é ler visualmente uma função específica, mais rápido podemos seguir em frente durante a manutenção do software. Com isso dito, eu gosto de separar grandes funções em...
A geração automática de documentação pode ser feita com uma variedade de ferramentas, sendo o GhostDoc um dos mais importantes. No entanto, por definição, tudo o que gera é redundante. Ele examina os nomes dos métodos, classes, etc. e produz o inglês que pode explicá-los mais detalhadamente. Na...
Estou escrevendo uma documentação do usuário (um POP) que envolve programas de terceiros que estou tentando descrever bem. Um desses programas é um servidor que oferece poucas indicações de inicialização, além de um gráfico que é exibido durante sua rotina de inicialização / inicialização. Como...
Às vezes me encontro em situações em que a parte do código que estou escrevendo é (ou parece ser ) tão evidente que seu nome seria basicamente repetido como um comentário: class Example { /// <summary> /// The location of the update. /// </summary> public Uri UpdateLocation { get;...
Quando você usa ferramentas como jsdocs , ele gera arquivos HTML estáticos e seus estilos na sua base de código com base nos comentários no seu código. Esses arquivos devem ser verificados no repositório Git ou devem ser ignorados com
Um dos principais objetivos das empresas de desenvolvimento de software é aumentar o fator Bus. Isso também é defendido em uma palestra organizada pelo Google . Isso significa que você deve codificar e documentar tudo de forma que, se você for atropelado no ônibus amanhã, o projeto ainda possa...
Parece haver aversão a escrever até a documentação mais básica. Nosso projeto READMEs é relativamente vazio. Não existem listas de dependências atualizadas nos documentos. Existe algo que eu não conheço no setor que faz com que os programadores não gostem de escrever documentação? Posso digitar...
Ao trabalhar no código, enfrento muitos dos mesmos desafios que meus colegas de equipe, e escrevi algumas funções e classes úteis, e eles também. Se houver uma boa comunicação, ouvirei falar de algo maravilhoso que alguém montou e, seis meses depois, quando precisar, talvez me lembre e chame essa...
Eu me pego escrevendo (espero) comentários úteis na documentação de código (C ++) do tipo: The reason we are doing this is... A razão pela qual eu uso "nós" em vez de "eu" é porque faço muita escrita acadêmica onde "nós" é frequentemente preferido. Então aqui está a pergunta. Existe um bom...
O programa de CS da minha escola evita qualquer menção à programação orientada a objetos, por isso tenho lido algumas coisas sozinho para complementá-la - especificamente, Construção de Software Orientada a Objetos , de Bertrand Meyer. Meyer defende repetidamente que as classes devem ocultar o...