Perguntas sobre 'documentation'

10
respostas

Como tornar uma base de código grande mais fácil de entender para novos programadores

Suponha que estou desenvolvendo um projeto relativamente grande. Eu já documentei todas as minhas classes e funções com o Doxygen, no entanto, tive a idéia de colocar "notas do programador" em cada arquivo de código-fonte. A ideia por trás di...
01.08.2015 / 00:33
0
respostas

Meu chefe quer uma explicação narrada em inglês, linha por linha, de nosso código

Fui especificamente solicitado a dar uma explicação ou comentário linha a linha (ou, conforme apropriado - por exemplo, imagem por imagem, etc.) que meu chefe queira ler e seguir. Como ele não é um programador, ele não pode seguir o código e...
24.10.2011 / 16:09
4
respostas

Qual é o número de telefone equivalente de example.org?

O padrão RFC 2606 reserva os nomes de domínio exemplo. org , example.net e example.com o propósito de ser usado como exemplos na documentação. O que é um equivalente para um número de telefone (incluindo o código do país) que pode ser u...
07.08.2018 / 18:32
13
respostas

Quais são os exemplos de comentários que informam por que, em vez de como ou o quê? [fechadas]

Em primeiro lugar, nesta questão, gostaria de ficar longe da polêmica sobre se o código-fonte comentando é bom ou ruim. Eu só estou tentando entender mais claramente o que as pessoas querem dizer quando falam sobre comentários que dizem por que,...
09.08.2013 / 08:51
12
respostas

O histórico de commits deve ser usado para transmitir informações críticas aos desenvolvedores?

Durante uma reunião sobre a reversão de um SDK de terceiros da versão mais recente, observou-se que nossos desenvolvedores já sinalizaram no histórico de confirmações que a versão mais recente não deve ser usada. Alguns desenvolvedores argume...
29.07.2014 / 15:59
16
respostas

O que há de errado com comentários que explicam código complexo?

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 (reescrito às minhas próprias palavras)...
01.09.2014 / 02:28
17
respostas

Os comentários TODO fazem sentido? [fechadas]

Estou trabalhando em um projeto bastante grande e tenho a tarefa de fazer algumas traduções para ele. Havia toneladas de rótulos que não foram traduzidos e enquanto eu estava vasculhando o código eu encontrei este pequeno pedaço de código //T...
11.11.2013 / 10:46
15
respostas

Vou deixar meu emprego por causa da nossa plataforma: como posso deixar uma explicação produtiva disso? [fechadas]

Estou planejando deixar meu emprego atual porque estamos bloqueados para usar o Blub , com um framework corporativo do Blub e um servidor web de nível Blub, em hospedagem compartilhada medíocre. Meus colegas de trabalho são amigáveis e meu chef...
31.03.2012 / 19:34
10
respostas

Existe algo como ter muitas funções / métodos privados?

Eu entendo a importância de um código bem documentado. Mas também entendo a importância do código auto-documentável . Quanto mais fácil for ler visualmente uma função específica, mais rápido poderemos avançar durante a manutenção do software....
14.02.2011 / 00:26
13
respostas

O código com comentários pode ser uma documentação valiosa?

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...
11.03.2013 / 10:36