Skip to main content
adicionou 187 caracteres ao conteúdo
Fonte Link
Maniero
  • 484,4mil
  • 94
  • 1,3mil
  • 2,2mil

Coloquei no GitHub para referência futura.

Note que é uma chamada, que é ainda pior documentar o uso. Se fosse na definição do método e explicasse porque ele é necessário, como ele age no sistema, aí tudo bem. Mas isto não só não era necessário, como não era feito por ninguém.

Note que é uma chamada, que é ainda pior documentar o uso. Se fosse na definição do método e explicasse porque ele é necessário, como ele age no sistema, aí tudo bem. Mas isto não só não era necessário, como não era feito por ninguém.

Coloquei no GitHub para referência futura.

Note que é uma chamada, que é ainda pior documentar o uso. Se fosse na definição do método e explicasse porque ele é necessário, como ele age no sistema, aí tudo bem. Mas isto não só não era necessário, como não era feito por ninguém.

Commonmark migration
Fonte Link

#Documentação

Documentação

#Códigos expressivos

Códigos expressivos

#HTML e CSS

HTML e CSS

#Conclusão

Conclusão

#Documentação

#Códigos expressivos

#HTML e CSS

#Conclusão

Documentação

Códigos expressivos

HTML e CSS

Conclusão

adicionou 2 caracteres ao conteúdo
Fonte Link
Maniero
  • 484,4mil
  • 94
  • 1,3mil
  • 2,2mil

A maioria do que eu poderia dizer já foi dito nas respostas aqui e em minha resposta nessa pergunta. Leia também as outras respostas lá, de uma maneira geral concordo com elas. Não acho que o que foi exposto na pergunta citada sirva só para C#. Alguns, alguns pontos sim, mas quase todos são universais.

Não confunda comentários com documentação. Documentar as classes e métodos mesmo usando o mecanismo de comentários não devem ser interpretados como comentários. Esta documentação é mais fácil manter sincronizada com o código porque ela só documenta o contrato. E, e contratos não devem ser mudados. Mas se o contrato for mudado assim mesmo, certamente haverá muitos testes e precisará ser comunicado para todos os usuários. Certamente a mudança na documentação não será esquecida. E se for, sua equipe está toda lascada mesmo, entrega pra deus :)

Documentação deve fornecer informações relevantes. Leia a documentação de APIs conhecidas queque têm fama de serem bem documentadas para ver o que é relevante. Colocar o óbvio não ajuda nada. Um comentário bobo só para dizer que documentou não serve para muita coisa. Deve haver explicação das implicações do uso daquela classe ou método. O que pode dar errado, quando usar e não usar. Porque aquilo existe, especialmente se parecer que não deveria existir. Documentar significa informar todos os aspectos daquilo, todos os dados importantes para o contrato, como parâmetros, retorno, exceções possíveis.

Para aprender só não vale olhar a documentação do PHP que é muito ruim :) Mentira, ela é melhor do que a maioria das documentações que as pessoas fazem. Ela só não é tão boa quanto algumas outras muito boas, que são exemplos de documentação bem feita. Embora nenhuma seja nota 10 também. Documentar, documentar bem é difícil.

Mas também tem que ver o custo de documentar isto. Nem, nem sempre vale o esforço. Isto será muito grande? É muito complicado acompanhar sem documentação? Será que não dá para simplificar a arquitetura para evitar ter que documentar tanto? Muitas vezes não precisa de tudo o que foi feito. Dá para tornar privadas algumas partes e tirar da API? Será usado por muita gente? Por muito tempo?

Você não percebe que as pessoas tem dificuldades em comentar? Parece um fardo fazer isto. E é algo bem mais fácil e menos trabalhoso que codificar. Talvez, não tenho estudos sobre o assunto, seja porque subconscientemente as pessoas sabem que aquilo não serserve para nada. Aí elas deixam de fazer quando o comentário é realmente necessário. O cérebro é muito confuso. Por isto propagandas usam esta falha para associar produtos com sentimentos bons. Por isto a gamificaçãogamificação funciona. Você tem que treinar seu cérebro para aceitar a importância dos comentários necessários e não deixar ele se confundir com a parte sábia dele que diz que comentário devem ser evitados.

Uma coisa que eu aprendi é que a pessoa que não consegue programar direito não vai conseguir comentar direito. Por isto muitos comentários não só falam o óbvio mas fazem o oposto, falam coisacoisas que não condizem com a realidade. Ela muitas vezes não entende o que ela está fazendo. Ela até sabe que o resultado está sendo produzindo mas ela não entende a semântica daquilo. E comentário, mesmo os que estamos dizendo que não são bons, servem para dar mais semântica ao que está sendo feito. Se o programador não sabe definir com clareza o que ocorre de fato ali, o comentário sairá errado. Eu mesmo depois de mais de 3035 anos de experiência tenho dificuldades de entender totalmente o problema que estou lidando quando é um problema novo para mim. Um exemplo de como é fácil entender errado uma coisa pode ser vista em mais uma excelente resposta do Eric Lippert.

A maioria do que eu poderia dizer já foi dito nas respostas aqui e em minha resposta nessa pergunta. Leia também as outras respostas lá, de uma maneira geral concordo com elas. Não acho que o que foi exposto na pergunta citada sirva só para C#. Alguns pontos sim, mas quase todos são universais.

Não confunda comentários com documentação. Documentar as classes e métodos mesmo usando o mecanismo de comentários não devem ser interpretados como comentários. Esta documentação é mais fácil manter sincronizada com o código porque ela só documenta o contrato. E contratos não devem ser mudados. Mas se o contrato for mudado assim mesmo, certamente haverá muitos testes e precisará ser comunicado para todos os usuários. Certamente a mudança na documentação não será esquecida. E se for, sua equipe está toda lascada mesmo, entrega pra deus :)

Documentação deve fornecer informações relevantes. Leia a documentação de APIs conhecidas que têm fama de serem bem documentadas para ver o que é relevante. Colocar o óbvio não ajuda nada. Um comentário bobo só para dizer que documentou não serve para muita coisa. Deve haver explicação das implicações do uso daquela classe ou método. O que pode dar errado, quando usar e não usar. Porque aquilo existe, especialmente se parecer que não deveria existir. Documentar significa informar todos os aspectos daquilo, todos os dados importantes para o contrato, como parâmetros, retorno, exceções possíveis.

Para aprender só não vale olhar a documentação do PHP que é muito ruim :) Mentira, ela é melhor do que a maioria das documentações que as pessoas fazem. Ela só não é tão boa quanto algumas outras muito boas, que são exemplos de documentação bem feita. Embora nenhuma seja nota 10 também. Documentar bem é difícil.

Mas também tem que ver o custo de documentar isto. Nem sempre vale o esforço. Isto será muito grande? É muito complicado acompanhar sem documentação? Será que não dá para simplificar a arquitetura para evitar ter que documentar tanto? Muitas vezes não precisa de tudo o que foi feito. Dá para tornar privadas algumas partes e tirar da API? Será usado por muita gente? Por muito tempo?

Você não percebe que as pessoas tem dificuldades em comentar? Parece um fardo fazer isto. E é algo bem mais fácil e menos trabalhoso que codificar. Talvez, não tenho estudos sobre o assunto, seja porque subconscientemente as pessoas sabem que aquilo não ser para nada. Aí elas deixam de fazer quando o comentário é realmente necessário. O cérebro é muito confuso. Por isto propagandas usam esta falha para associar produtos com sentimentos bons. Por isto a gamificação funciona. Você tem que treinar seu cérebro para aceitar a importância dos comentários necessários e não deixar ele se confundir com a parte sábia dele que diz que comentário devem ser evitados.

Uma coisa que eu aprendi é que a pessoa que não consegue programar direito não vai conseguir comentar direito. Por isto muitos comentários não só falam o óbvio mas fazem o oposto, falam coisa que não condizem com a realidade. Ela muitas vezes não entende o que ela está fazendo. Ela até sabe que o resultado está sendo produzindo mas ela não entende a semântica daquilo. E comentário, mesmo os que estamos dizendo que não são bons, servem para dar mais semântica ao que está sendo feito. Se o programador não sabe definir com clareza o que ocorre de fato ali, o comentário sairá errado. Eu mesmo depois de mais de 30 anos de experiência tenho dificuldades de entender totalmente o problema que estou lidando quando é um problema novo para mim. Um exemplo de como é fácil entender errado uma coisa pode ser vista em mais uma excelente resposta do Eric Lippert.

A maioria do que eu poderia dizer já foi dito nas respostas aqui e em minha resposta nessa pergunta. Leia também as outras respostas lá, de uma maneira geral concordo com elas. Não acho que o que foi exposto na pergunta citada sirva só para C#, alguns pontos sim, mas quase todos são universais.

Não confunda comentários com documentação. Documentar as classes e métodos mesmo usando o mecanismo de comentários não devem ser interpretados como comentários. Esta documentação é mais fácil manter sincronizada com o código porque ela só documenta o contrato, e contratos não devem ser mudados. Mas se o contrato for mudado assim mesmo, certamente haverá muitos testes e precisará ser comunicado para todos os usuários. Certamente a mudança na documentação não será esquecida. E se for, sua equipe está toda lascada mesmo, entrega pra deus :)

Documentação deve fornecer informações relevantes. Leia a documentação de APIs conhecidas que têm fama de serem bem documentadas para ver o que é relevante. Colocar o óbvio não ajuda nada. Um comentário bobo só para dizer que documentou não serve para muita coisa. Deve haver explicação das implicações do uso daquela classe ou método. O que pode dar errado, quando usar e não usar. Porque aquilo existe, especialmente se parecer que não deveria existir. Documentar significa informar todos os aspectos daquilo, todos os dados importantes para o contrato, como parâmetros, retorno, exceções possíveis.

Para aprender só não vale olhar a documentação do PHP que é muito ruim :) Mentira, ela é melhor do que a maioria das documentações que as pessoas fazem. Ela só não é tão boa quanto algumas outras muito boas, que são exemplos de documentação bem feita. Embora nenhuma seja nota 10 também, documentar bem é difícil.

Mas também tem que ver o custo de documentar isto, nem sempre vale o esforço. Isto será muito grande? É muito complicado acompanhar sem documentação? Será que não dá para simplificar a arquitetura para evitar ter que documentar tanto? Muitas vezes não precisa de tudo o que foi feito. Dá para tornar privadas algumas partes e tirar da API? Será usado por muita gente? Por muito tempo?

Você percebe que as pessoas tem dificuldades em comentar? Parece um fardo fazer isto. E é algo bem mais fácil e menos trabalhoso que codificar. Talvez, não tenho estudos sobre o assunto, seja porque subconscientemente as pessoas sabem que aquilo não serve para nada. Aí elas deixam de fazer quando o comentário é realmente necessário. O cérebro é muito confuso. Por isto propagandas usam esta falha para associar produtos com sentimentos bons. Por isto a gamificação funciona. Você tem que treinar seu cérebro para aceitar a importância dos comentários necessários e não deixar ele se confundir com a parte sábia dele que diz que comentário devem ser evitados.

Uma coisa que eu aprendi é que a pessoa que não consegue programar direito não vai conseguir comentar direito. Por isto muitos comentários não só falam o óbvio mas fazem o oposto, falam coisas que não condizem com a realidade. Ela muitas vezes não entende o que ela está fazendo. Ela até sabe que o resultado está sendo produzindo mas ela não entende a semântica daquilo. E comentário, mesmo os que estamos dizendo que não são bons, servem para dar mais semântica ao que está sendo feito. Se o programador não sabe definir com clareza o que ocorre de fato ali, o comentário sairá errado. Eu mesmo depois de mais de 35 anos de experiência tenho dificuldades de entender totalmente o problema que estou lidando quando é um problema novo para mim. Um exemplo de como é fácil entender errado uma coisa pode ser vista em mais uma excelente resposta do Eric Lippert.

replaced http://stackoverflow.com/ with https://stackoverflow.com/
Fonte Link
Carregando
replaced http://pt.stackoverflow.com/ with https://pt.stackoverflow.com/
Fonte Link
Carregando
removeu 12 caracteres do conteúdo
Fonte Link
Maniero
  • 484,4mil
  • 94
  • 1,3mil
  • 2,2mil
Carregando
adicionou 1869 caracteres ao conteúdo
Fonte Link
Maniero
  • 484,4mil
  • 94
  • 1,3mil
  • 2,2mil
Carregando
adicionou 390 caracteres ao conteúdo
Fonte Link
Maniero
  • 484,4mil
  • 94
  • 1,3mil
  • 2,2mil
Carregando
Fonte Link
Maniero
  • 484,4mil
  • 94
  • 1,3mil
  • 2,2mil
Carregando