Discurso de entrada. Traduzido corretamente, deve ser lido como um testemunho das melhores práticas em relação à codificação em geral. Desfrute de toda a sua glória enraivecida.
Comente de forma consistente, comente sempre. É isso mesmo. Me incomoda ter que suportar código legado que tem pouco ou nada para referência que, Deus me livre, alguém que não seja o autor original possa precisar. Não consigo nem contar quantas vezes salvei meu próprio bacon descrevendo as principais etapas a serem executadas em meu próprio código; é muito bom e quase não leva tempo. Além disso, o velho ditado de
“se você não pode segurar seu argumento contra as críticas, então não é muito um argumento”
realmente se aplica.
Mesmo se você achar que é bom demais para comentar por si mesmo, então perceba que não está trabalhando no vácuo; você trabalha para uma equipe. Ou é uma equipe que você conhece e contra a qual não deveria querer trabalhar, ou é uma equipe que ainda não existe e seu código @ $$ de merda precisará de suporte depois que você se for.
É tudo o que tenho. Principais marcos e / ou intenções para blocos de código. Você não precisa segurar as mãos, mas definitivamente declarar o que deve estar acontecendo, talvez por que, se estiver com vontade, e quaisquer detalhes ou saídas.
Ao invés de
“sê simpático, rebobina”,
seja gentil, comente seu maldito código!