Perguntas com a marcação «documentation»

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 códigos mal escritos". Minha pergunta é a …

236 programming-practices  documentation  comments 

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 inglês. …

155 documentation 

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 …

112 documentation  standards  help-documentation 

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 específica …

104 documentation  large-scale-project 

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, deveria ter sido …

94 version-control  documentation 

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 comentários para si …

86 documentation  comments 

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()); boutique.setNom(fluxBoutique.getNom()); boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.persist(boutique); } else { boutique.setSite(site); boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo()); boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl()); boutique.setNom(fluxBoutique.getNom()); //boutique.setSelected(false); boutique.setIdWebSC(fluxBoutique.getId()); boutique.setDateModification(new Date()); boutiqueDao.merge(boutique); } Há uma linha comentada aqui. Mas acho que isso torna o código mais claro, …

83 documentation  comments 

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 …

78 documentation  comments 

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 …

72 project-management  documentation 

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 …

66 career-development  documentation 

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 outras menores. Mas …

63 programming-practices  code-quality  documentation 

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 melhor das …

60 documentation  automation  automatic-programming 

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 desenvolvedor, usei essa janela como …

59 documentation  component  jargon 

À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; set; …

54 programming-practices  documentation  language-agnostic 

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 .gitignore?

49 git  documentation