Por que algumas bibliotecas opensouce não têm comentários?

8

Não sei se isso acontece com a maioria das bibliotecas de código-fonte aberto, mas muitas delas eu conheço e uso (por exemplo, OpenSSL, Webkit, ...) todas elas não têm comentários ou contêm muito poucos comentários.

Sem mencionar seus poucos documentos, é difícil ler o código fonte. Mal podemos entender o que significa uma variável membro ou o que essa função faz. Parece ser contra a prática padrão de codificação

Por que é que? Como as pessoas podem colaborar com esse código-fonte aberto com muito poucos comentários?

onmyway133
fonte
2
Comentários não especificamente são importantes, mas a legibilidade do código. Mas acho que você quis dizer isso, então sugiro que reformule sua pergunta. Aqui estava uma pergunta relacionada (não duplicada). programmers.stackexchange.com/questions/185923/…
Doc Brown
Além do comentário feito por @DocBrown acima, você deseja garantir que seu código também esteja bem estruturado (por exemplo, etapas coerentes nas instruções). O código legível e bem estruturado elimina a necessidade de colocar bilhões de linhas de comentário desnecessariamente. E os projetos / bibliotecas OpenSource costumam ser para usuários intermediários e avançados da linguagem de programação / script. Se alguém acabou de aprender a digitar "Hello World" e entrar neles, provavelmente nenhum comentário ou código será significativo para eles. Os comentários são bons e necessários, somente quando você acha que será ambíguo para um usuário normal.
hagubear
Observe que ter poucos comentários não significa necessariamente que o código deve ser difícil de ler. Idealmente, o código deve ser legível sem comentários. Veja, por exemplo, programmers.stackexchange.com/questions/1/…
sleske

Respostas:

15

Escrever código fonte é divertido.

Escrever documentação e comentar códigos é menos divertido.

Quando um desenvolvedor trabalha em uma empresa que aplica bons comentários e documentação, não há escolha: esse desenvolvedor os escreve ou corre o risco de ser demitido.

Quando um desenvolvedor contribui para um projeto de código aberto, ele o faz de graça e principalmente por diversão. Não há ninguém para forçar esse desenvolvedor a fazer coisas que ele não está disposto a fazer, como escrever documentação e comentários.

É por isso que muitos projetos de código aberto não possuem documentação e comentários extensivos.


Como as pessoas ainda podem contribuir para projetos de código aberto sem documentação ou comentários?

  • Se o código fonte for de alta qualidade, os comentários não serão necessários demais. Os comentários de interfaces públicas e a documentação são especialmente úteis para os consumidores do projeto, ou seja, desenvolvedores que simplesmente usam bibliotecas, não contribuem para eles.

  • Não há fator de produtividade envolvido. Estou trabalhando em uma empresa em que a base de código real não possui testes de unidade, documentação e comentários. Passo muito tempo descobrindo o que um método 600-LOC está fazendo ou codificando coisas que já foram feitas, mas que não podem ser descobertas por causa da falta de documentação; portanto, na maioria das vezes, estou simplesmente desperdiçando o dinheiro da empresa em vez de fazer algo valioso.

    Por outro lado, para um projeto de código aberto, não importa se um dos colaboradores perdeu uma semana devido à falta de documentação ou comentários adequados. A pior coisa que pode acontecer é que esse colaborador saia do projeto.

    Descobrir código sem comentários ou documentação pode até ser desafiador, ou seja, atrair alguns colaboradores, em vez de desencorajá-los.

  • Em projetos empresariais, não é incomum um desenvolvedor ser forçado a trabalhar em todos os aspectos de um produto e, alguns anos depois, ter que conhecer quase todo o sistema. Em um projeto de código aberto, ninguém o obriga a saber tudo. Você pode simplesmente contribuir com uma parte minúscula e ter um excelente conhecimento dessa parte, sem a necessidade de documentação.

Arseni Mourzenko
fonte
3
"Quando um desenvolvedor contribui para um projeto de código aberto, ele o faz de graça e principalmente por diversão". Existem inúmeros projetos de código aberto com os quais as pessoas são pagas para trabalhar. Duvido que os engenheiros da IBM que trabalham com o kernel do Linux façam isso de graça; Eu acho que é uma aposta segura que as pessoas que desenvolveram o MySQL foram pagas para fazê-lo; e assim por diante. Não estou dizendo que isso é o mais comum ou até mesmo o mais comum, mas certamente não é justo dizer que, apenas porque o código será tornado público, o programador não é pago para fazer o trabalho. Personalizações ainda mais.
um CVn 01/07/19
2
@ MichaelKjörling: +1. Na verdade, eu esqueci esse caso. A propósito, seria interessante comparar os comentários no código-fonte aberto, onde os desenvolvedores foram pagos versus os comentários no código-fonte aberto, feitos de graça.
Arseni Mourzenko
2

Vários motivos.

  • Escrever documentação não é divertido e, para muitos projetos, a base de usuários é a equipe de programação; todo mundo sabe do que se trata o código; portanto, a documentação não é realmente vista como um aspecto importante do projeto.
  • A documentação pode (e vai) ficar desatualizada, e a documentação desatualizada é pior do que nenhuma. Isso significa que a documentação é uma responsabilidade extra e pode afetar a flexibilidade da sua base de código (mais documentação significa para qualquer alteração que você precise atualizar o código e a documentação). Especialmente para projetos de código aberto muito específicos, esse é realmente um argumento válido para obter o mínimo de documentação e, em vez disso, escrever código legível.
  • A economia do software de código aberto é diferente. Embora seja bom ter colaboradores em seu projeto, muitos projetos são do tipo scratch-an-itch que o autor escreveu para resolver um problema específico e depois jogou fora como está. Como você está basicamente comendo migalhas de pão de outra pessoa, a atitude é que você não está em posição de exigir nada, muito menos de documentação.
tdammers
fonte
2

Como as pessoas podem colaborar com esse código-fonte aberto com muito poucos comentários

Supondo que você quis dizer "Como as pessoas podem colaborar com esse código de código aberto que é difícil de ler" - bem, acho que um projeto de código aberto com código incorreto simplesmente terá menos colaboradores do que poderia ter com um bom código. Mas não esqueça que a legibilidade do código está sempre nos olhos de quem vê, e a maioria do código-fonte aberto não é tão ruim que você não possa entender pelo menos um pouco ou as intenções de algumas funções e classes.

Frequentemente, quando você deseja contribuir com algo para um projeto de código aberto, não precisa entender tudo, apenas as partes em que deseja adicionar um recurso específico. Portanto, se um desenvolvedor precisar de um recurso ausente, ele provavelmente irá morder a bala, identificará as partes que precisa mudar, "decodificará" essas partes mentalmente e incluirá os novos recursos. Se ele é bom, ele também tentará revisar e refatorar as partes "decodificadas", mas acho que na prática isso acontecerá muito raramente.

Doc Brown
fonte
1
hmm, não tenho tanta certeza sobre código incorreto, o que significa menos contribuintes. O número de contribuidores, tanto ou mais, relacionados à estrutura e ao tipo do projeto, assim como ao código contido nele. Existe um código muito bom com apenas uma ou duas pessoas envolvidas, destinado a um pequeno nicho e coisas ruins que têm milhares de pessoas conectando-o com pouca supervisão ou supervisão por pessoas que não são boas codificadores (pense em todos esses jogos) e coisas que atraem crianças em idade escolar).
Jwenting 01/07
1
Sou a favor de "menos colaboradores que ele poderia ter ".
#
@Iserni: sim, acho que eu acho semelhante sobre isso, mudou a minha resposta em conformidade
Doc Brown
Eu concordo com @jwenting. Alguém olhou sob o capô do Wordpress ultimamente?
Radu Murzea