É “engraçado comentar” uma má prática ou não? [fechadas]

36

Eu quero perguntar se adicionar alguns "easter eggs" na documentação de origem é não profissional ou não. Provavelmente você leu o StackOverflow enquete para comentários engraçados em uma documentação de origem, e eu pessoalmente tropecei em muitas dessas coisas durante meu trabalho, incluindo coisas engraçadas (ou não) na documentação pública da API (por exemplo, este fraco BZZZTT !! 1! coisa na documentação pública do Android, posso dar pelo menos mais uma dúzia de exemplos) .

Eu não posso chegar a uma opinião final para mim, porque eu tenho argumentos contraditórios por mim mesmo.

Argumento Pro:

  • Pode animar alguém e tornar seu dia mais divertido / produtivo. Maior parte do código-fonte não precisa ser comentado de qualquer maneira (se o projeto é feito corretamente), porque o método específico (por exemplo) é auto-explicativo, ou se é um monte de códigos estranhos, ele não pode ser explicado de uma maneira significativa, portanto, uma piada engraçada não prejudica a possível informação que você pode obter do documento.

Argumento dos contras:

  • Se você é muito concentrado / frustrado, a última coisa que você precisa é a piada estúpida de alguém, em vez de lhe dar informações que você precisa sobre o código documentado, isso pode deixá-lo ainda mais frustrado. E a ideia 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 pensa que é engraçado / interessante / vale a pena perder tempo para lê-lo.

O que você acha?

    
por somebody 22.03.2011 / 12:14
fonte

11 respostas

12

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

Mas ... ninguém trabalha realmente a 100% durante todo o dia todos os dias (sites como este ficariam vazios se o fizéssemos) e o humor genuíno quebra o dia e ajuda a manter o moral.

Eu ainda votaria contra isso simplesmente porque todo comentário 'engraçado' que eu já li poderia muito bem ter sido hilário na época - mas eu ainda tenho que ver um que realmente engraçado, a maioria é apenas intrigante ou é um profundo na piada.

Se comentários engraçados fossem engraçados, isso mudaria minha opinião. Mas uma vez que você incentiva piadas, você incentiva palavrões, insultos ou malícia?

    
por 22.03.2011 / 12:33
fonte
70

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

Você deve sempre ser profissional em seus comentários, mas algum humor não mata o leitor.

Especialmente se o leitor for membro da sua equipe.

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

    
por 22.03.2011 / 12:24
fonte
8

Se tiver algum significado, não há problema em ser engraçado. Explicar algo em um comentário de uma maneira divertida é bom. No entanto, se é apenas algo engraçado e não contém nenhum valor real como um comentário, isso é simplesmente irritante. Tenha sempre em mente que o motivo dos comentários é tornar a manutenção mais eficiente. O humor não tem que entrar em conflito com isso, mas poderia se não fosse feito apropriadamente.

    
por 22.03.2011 / 12:46
fonte
8

O código é destinado a leitura ... muitas vezes.

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

    
por 22.03.2011 / 13:24
fonte
7

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

  • Isso dá uma vibe positiva ao seu código aparentemente chato.
  • Se você obtiver o seu tempo corretamente. Ele explicará muito melhor do que um comentário chato normal faria. Por "timing", 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). Este é 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 o seu código muito mais suportável. Claro que você deve primeiro se concentrar em escrever um bom código. Eu sinto que quando se está confiante com o código que eles escrevem, comentários engraçados são apenas um efeito colateral.

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

    
por 22.03.2011 / 12:52
fonte
6

Aqui está uma que eu 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)
    
por 22.03.2011 / 13:30
fonte
3

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

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

Comentários de códigos engraçados podem, às vezes, ser pouco profissionais e inadequados.

    
por 22.03.2011 / 13:41
fonte
3

Além do que já foi dito, se você está trabalhando em equipes internacionais, alguns de seus colegas estrangeiros podem não entender a piada, porque algumas das referências culturais locais ou palavras que não são compreendidas por alguém para quem o inglês é não língua nativa. A mesma coisa se aplica a projetos de código aberto.

    
por 22.03.2011 / 13:59
fonte
2

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

    
por 22.03.2011 / 12:38
fonte
2

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

    
por 22.03.2011 / 13:04
fonte
1

Depende, para tarefas na faculdade, eu estava quase sempre fazendo comentários engraçados, pois sabia que nunca seria usado e é apenas uma lição de casa.

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

Eu me lembro de fazer um pouco de programação na web, onde tive que evitar as incompatibilidades do navegador e falhas estranhas. Às vezes, terminava em comentários cheios de raiva e ódio nos arquivos .js .

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

Se o código for tão obscuro e ofuscante como o inferno (como o " inline classe "), é melhor eu estar usando comentários que eu vou me entender em alguns dias ...

    
por 22.03.2011 / 14:51
fonte