O “comentário engraçado” é uma prática ruim ou não? [fechadas]

Quero perguntar se a adição de alguns "ovos de páscoa" na documentação de origem não é profissional ou não. Provavelmente você já leu o StackOverflow pesquisa para comentários engraçados em uma documentação de origem, e eu pessoalmente tenho tropeçou em muitas coisas durante a minha trabalho, incluindo engraçado (ou não) o material na documentação da API pública (por exemplo, esta fraca BZZZTT !! 1! Coisa na documentação pública do Android, posso dar pelo menos uma dúzia de mais exemplos).

Não posso chegar a uma opinião final por mim mesma, porque tenho argumentos contraditórios por mim mesma.

Pro argumento:

• Pode animar alguém e tornar seu dia mais divertido / produtivo. Grande parte do código-fonte não precisa ser comentada de qualquer maneira (se o projeto for feito corretamente), porque o método específico (por exemplo) é auto-explicativo ou, se for uma pilha de códigos ruins, não pode ser explicado de maneira significativa, para que uma piada engraçada não prejudique as informações possíveis que você pode obter no documento.

Contras argumento:

• Se você está muito concentrado / frustrado, a última coisa que precisa é da piada estúpida de alguém, em vez de fornecer as informações necessárias sobre a parte do código documentado, isso pode deixá-lo ainda mais frustrado. E a idéia de como seria a documentação se todo mundo começar a fazer isso é horrível. Além disso, o cara que escreve a piada pode ser o único que acha engraçado / interessante / que vale a pena perder tempo para lê-la.

O que você acha?

Penso que comentários engraçados desperdiçam tempo - desperdiçam tempo para escrever, desperdiçam tempo para ler, desperdiçam tempo para mostrar aos colegas a observação engraçada que é (quase sempre) apenas intrigante e assim por diante.

Mas ... ninguém trabalha 100% o dia todo todos os dias (sites como esse estariam vazios se o fizéssemos) e o humor genuíno interrompe o dia e ajuda a manter o moral.

Eu ainda votaria contra isso simplesmente porque todo comentário "engraçado" que eu já li pode ter sido hilário na época - mas ainda não vi um que seja realmente engraçado, a maioria é apenas intrigante ou profundo. -gracejo.

Se comentários engraçados fossem realmente engraçados, isso mudaria de idéia. Mas uma vez que você incentiva piadas, você encoraja palavrões, insultos ou maldade?

Eu sou um grande fã de comentários engraçados .

Você deve sempre ser profissional nos seus comentários, mas um pouco de humor não mata o leitor.

Especialmente se o leitor for um membro de sua equipe.

O que eu mais não gosto, são desenvolvedores que se levam muito a sério. Acho que devemos nos divertir no trabalho, ou o trabalho não vale a pena.

Se tiver significado, é bom ser engraçado. Explicar algo de um comentário de uma maneira divertida é bom. No entanto, se é apenas algo engraçado e não contém nenhum valor real como comentário, isso é apenas irritante. Lembre-se sempre de que o motivo dos comentários é tornar a manutenção mais eficiente. O humor não precisa entrar em conflito com isso, mas pode, se não for feito adequadamente.

O código é para leitura ... muitas vezes.

Quantas piadas você sabe que são engraçadas depois da centésima contagem?

Comentários engraçados são ótimos.

• Ele dá uma vibração positiva ao seu código aparentemente chato.
• Se você acertar o tempo . É muito melhor explicar do que um comentário chato normal faria. Por 'tempo' aqui, quero dizer a relevância para o código abaixo do comentário.
• Seu código será lembrado por muitos, porque as emoções recebem um lugar melhor na memória (humana). Esse é um ótimo truque se você quiser que mais pessoas trabalhem com você em um projeto de código aberto.
• Geralmente útil em comentários. Isso torna seu código muito mais suportável. Claro que você deve primeiro se concentrar em escrever um bom código. Sinto que quando alguém está confiante com o código que escreve, comentários engraçados são apenas um efeito colateral.

Só não seja engraçado como esse cara ;)

Aqui está um que escrevi às duas da manhã ("DQ" são as iniciais da minha empresa):

// Twas the night before go-live and all through DQ
// the devs were all crying and yes, this means you.
// Keys had been saved with both hyphens and 'scores
// which left this programmer with finger pad sores.
// The solution I crafted, you'll likely find lacking:
// to OR them together with judicuous hacking.

$hyphenated = str_replace('_','-',$data_type_key);
$underscored = str_replace('-','_',$data_type_key);
// (and then see line 46)

Se você estivesse revendo seu código-fonte na frente do cliente, ficaria envergonhado?

Nenhuma das respostas atuais parece levar isso em consideração. Alguns clientes não têm senso de humor e consideram as piadas como um indicador de que você não leva seu trabalho a sério. Eles deduzirão que você é descuidado com seu trabalho.

Às vezes, comentários engraçados sobre códigos podem ser pouco profissionais e inadequados.

Além do que já foi dito, se você estiver trabalhando em equipe internacional, alguns de seus colegas estrangeiros podem não entender a piada, porque algumas das referências culturais locais ou algumas palavras são interpretadas por alguém para quem o inglês não é o idioma nativo . O mesmo se aplica a projetos de código aberto.

Se for eficiente e não desperdiçar o tempo dos leitores (na leitura / compreensão), não vejo problema com um pouco de humor.

Assim como as piadas do mundo real, se você as faz o tempo todo, não é engraçado, nem produtivo nem profissional. Mas há uma hora e um lugar para todas as piadas, e há uma hora e um lugar no código. Assim como no mundo real, é saber onde, quando e como fazer a piada.

Depende, para tarefas na faculdade, eu quase sempre fazia comentários engraçados, pois sabia que nunca seriam usados ​​e é apenas uma tarefa de casa.

Para projetos mais sérios, eu ainda os usaria aqui e ali, mas não como predominantes, para que seja irritante ou difícil de entender, desafiando o objetivo do comentário.

Lembro-me de fazer um pouco de programação na Web, onde tive que evitar incompatibilidades no navegador e falhas estranhas. Às vezes, terminava em comentários cheios de raiva e ódio nos .jsarquivos.

Minha regra básica é: se é algo óbvio o que a seção de código faz, COMENTÁRIOS ENGRAÇADOS LIGAM!

Se o código é tão obscuro e ofuscante como o inferno (como a " classe inline "), é melhor eu usar comentários. Vou me entender daqui a alguns dias ...