É permitido colocar um link para os sites de Q & A nos comentários de um programa?

15

Em algumas bases de código, você pode ver comentários dizendo coisas como:

 // Workaround for defect 'xxx', (See bug 1434594 on Sun's bugparade)

Então, tenho algumas perguntas, mas todas estão relacionadas.

Não há problema em colocar um link para perguntas do SO nos comentários de um programa:

 // We're now mapping from the "sorted-on column" to original indices.
 //
 // There's apparently no easy way to do this in Java, so we're
 // re-inventing a wheel.
 //
 // (see why here, in SO question: http://stackoverflow.com/questions/951848)

Você faz isso?

E quais são os inconvenientes disso? (veja meu primeiro comentário para uma terrível desvantagem)

    
por Tristan St. 17.05.2010 / 18:42
fonte

5 respostas

7

Eu fiz isso, talvez não especificamente para o Stack Overflow, mas para blogs técnicos, fóruns, Usenet, Grupos do Google ou outros lugares onde o "por que fiz isso" pode não estar totalmente claro no contexto.

Eu não vejo por que usar SO como isso seria uma coisa ruim, a menos que eles arquivem e eliminem velhas perguntas (o que eu não acho que façam, mas não tenho certeza) - mas mesmo que , não é pior do que qualquer outro site.

Se você está realmente preocupado com isso, sempre é possível tirar screenshots ou fazer o download dessas páginas como texto (ou ter o trabalho de obter as imagens, folhas de estilo etc.) e salvá-las em um repositório de conhecimento na sua empresa , anexando um identificador único a ele e colocando esse identificador exclusivo em seus comentários para permitir que você faça referência mais tarde - então você teria um lugar consistente para esse tipo de coisa. Mas isso pode ser um exagero, dependendo da complexidade e importância do seu código.

    
por 17.05.2010 / 18:47
fonte
5

Geralmente, a melhor maneira de criar este link é através do sistema de versão e / ou do sistema de rastreamento de bugs. O requisito para isso funcionar é que você pode vincular seu código com precisão ao rastreador de bugs ou ao local no sistema de versão onde você coloca seus comentários.

    
por 17.05.2010 / 18:46
fonte
5

Idealmente, o seu código não necessita de tais comentários porque está bem estruturado, etc. Mas, sim, quando a sua situação é menos do que ideal, é aceitável colocar comentários como este. E os links para stackoverflow.com são tão bons (e muitas vezes melhores!) Do que outros.

Espero que sejam comentários temporários e você poderá voltar e melhorar o código e retirar esses comentários .

Ainda não coloquei um link do StackOverflow.com no meu código. Eu tento evitar colocar links no código, já que é um cheiro ruim, mas quando chegar a hora eu não hesitarei.

Editar : Acho que minha resposta acima dá a impressão de que a necessidade de comentários como esse é evitável. Claro que às vezes é não evitável; é um bug em uma biblioteca ou um design de API insatisfatório sobre o qual você não tem controle. Comentários como este, incluindo links, são muito úteis para o próximo desenvolvedor aparecer.

    
por 17.05.2010 / 18:45
fonte
2

Eu vejo como escrever um trabalho de pesquisa. Se eu usar as ideias de outra pessoa, preciso dar crédito a essas ideias. Eu usei uma resposta do stackoverflow no meu código antes, e adicionei o link para os comentários do método.

Como alguém mencionou, o SO é um estilo wiki, então é possível que ele mude, mas geralmente a ideia ainda deve ser a mesma.

Você ainda deve dar crédito aos outros quando usar as ideias deles.

    
por 03.02.2012 / 10:03
fonte
1

Se você precisou implementar uma solução alternativa, e não é óbvio por que a implementação foi feita de uma maneira específica, então um comentário deve ser deixado para identificar as razões pelas quais. Eu acho que colocar um link para uma referência online é bom, mas você realmente precisa ter feito o seu comentário sucinto, mas completo o suficiente para que o link forneça apenas uma explicação expandida caso o leitor sinta a necessidade de checar seu raciocínio.

Se, por outro lado, o código foi copiado textualmente, então um link para a fonte original é apenas justo, e pode ser necessário dependendo do texto da licença sob a qual você foi autorizado a copiar o trabalho do autor original.

    
por 03.02.2012 / 11:16
fonte

Tags