Comentários no código boa ou má prática? 🤔

Concordo do POR QUE e nesses casos é realmente muito bom, alguns exemplos do código fonte do TabNews, onde numa migration sobre a criação da tabela users eu anotei o POR QUE de certos valores:

    // Why 254 in length? https://stackoverflow.com/a/1199238
    email: {
      type: 'varchar(254)',
      notNull: true,
      unique: true,
    },

    // Why 60 varchar? https://forums.phpfreaks.com/topic/293405-recommended-sql-datatype-for-bcrypt-hash/#comment-1500831
    password: {
      type: 'varchar(60)',
      notNull: true,
    },

...

    // Why "with timezone"? https://stackoverflow.com/a/20713587
    created_at: {
      type: 'timestamp with time zone',
      notNull: true,
      default: pgm.func("(now() at time zone 'utc')"),
    },

https://github.com/filipedeschamps/tabnews.com.br/blob/b620df28fe4ece27cc0b44bf62614d189071fc2b/infra/migrations/1632278997051_create-user-table.js#L17-L41

E pensando agora, o ideal seria apontar para uma issue permanente dentro do projeto com trechos do artigo original (mas ainda linkando para ele), para caso o link se tornar indisponível, você ainda ter a fração que importa sob seu controle.

Documente o POR QUE, não apenas o QUE

Concordo.

Comentários óbvios demais geralmente não acrescentam muita coisa e só poluem o código:

int idade = 42; // idade
if (aniversario()) {
    // se fez aniversário, aumenta 1 ano na idade
    idade++;
}

Então concordo que, em geral, o por que é mais importante do que o que. Em vez de dizer "fazendo X", é melhor dizer "fazendo X por causa da regra Y (link da especificação)".

Mas tudo tem exceção, tem vezes em que o que não é tão óbvio e merece um comentário (mas aí pode ser um sintoma de que aquele trecho está confuso demais e precisa ser refatorado - ou não, cada caso é um caso).

O problema é que querem transformar o "clean code" em religião, né? E como sempre acontece nesses casos, o que importa não é o que (ou o porquê) está escrito, mas o meu (geralmente mal) entendimento sobre o que está escrito.

Dai eu saio internet afora dizendo que "todo comentario é pecado, porque 'Assim diz o livro de Clean Code...'"

Comentar o porquê, e não o que o código faz, é o conhecimento universal que se tem.

Existe só um grupo de pessoas muito antigo que aprendeu como comentar código nos anos 60 e não conseguiram se atualizar. Sim, naquela época fazia sentido comentar o que o código fazia, e os comentários foram inventados para isso.

Eu não lembro bem em que livro eu vi isso, ou livros, não lembro se tinha no Clean Code, mas está por todo lugar e a base dele fala o que você diz.

Não sei bem qual é a discordância forte que está tendo (pode indicar melhor?) porque não percebi qual é a afirmação a ser discordada, mas parece que concorda com o que "todo mundo" concorda.

Explicar as razões do código ser daquele jeito é correto, descrever o código não é.

Para tudo existe exceção, contexto é tudo, regras sem contexto são chamadas de "boa prática", por isso elas são ruins. Até comentar o que o código faz tem serventia no contexto certo.

Eu escrevi algumas respostas com mais detalhes, (não voui ficar me repetindo) e estou sempre aberto para aprender mais sobre o assunto:

• Por que não comentar o código?
• Como saber a medida certa de comentários?
• Comentários em código ao trabalhar em grupo
• Comentários pesam?
• O que são comentários WET?
• O que é uma documentação formal?

Farei algo que muitos pedem para aprender programar corretamente, gratuitamente. Para saber quando, me segue nas suas plataformas preferidas. Quase não as uso, não terá infindas notificações (links aqui).

já trabalhei em duas empresas onde cada uma seguia abordagens diferente para comentários, a primeira era obrigatório comentar cada linha para deixar "mais legivel", e a outra era totalmente contra comentários.

a primeira tinha uma certa dificuldade de manter o comentario atualizado, pois se você for refatorar o código, tem que refatorar o comentário junto, e isso é o que não acontecia, já lidei com casos onde estava escrito "pinta a div de vermelho" mas no trecho do código não fazia nada do que o comentário dizia. Além dos casos de pessoas que tem dificuldade em descrever o que algo faz e faz um comentário extremamento confuso.

códigos não comentádos te força a ler o código e entender realmente o que está acontecendo alí, se está muito dificil de entender está mais do que na hora de refatorar esse cara e deixa-lo mais legivel.

gostei mais de trabalhar sem comentários, comentários mentem e atrapalham

Esse é um dos temas que sempre terá discussão, já vi muitos falando também que o bom código não precisa de comentários, coisa que discordo completamente.

Por exemplo, um código que acredito que ninguém teria coragem de falar mal seria a implementação do sha256 na lib OpenSSL, porém, é possível entender esse código caso você não tenha acesso à documentação?

Por exemplo, em uma parte do código é definida a seguinte array:

[
        0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5,
        0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
        0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
        0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
        0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc,
        0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
        0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7,
        0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
        0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
        0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
        0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3,
        0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
        0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5,
        0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
        0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
        0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
    ]

Sem ter acesso à documentação, alguém consegue identificar de onde vem esses valores mágicos? Provavelmente não, agora se tiver a linha de comentário: (first 32 bits of the fractional parts of the cube roots of the first 64 primes 2..311): tudo fica muito mais claro.

Eu carrego comigo que código tem que contar uma história, como se fosse um livro mesmo (É meio filosófico, mas gosto de pensar assim), as variaveis e métodos precisam ser auto descritivas mas quando o nicho do negócio é muito especifico, os comentarios são uma mão na roda nesse processo, se forem padronizados claro.

O problema que vejo é que muitas pessoas usam comentarios como bloco de notas, coloca uma frase para que ela no futuro se lembre do que aconteceu naquele trecho sem pensar no que outras pessoas vão entender daquele comentário.

Uma forma legal de padronizar comentarios em JS é usando JSDocs por exemplo, você pode espeficicar o "POR QUE" de uma função ou arquivo e depois você pode até gerar uma doc disso e integrar no Github pages e ele ajuda muito até que vai fazer implementação do trecho.

Se você escreve O QUE o código está fazendo, é porque o código não está bem escrito.

Realmente, comentar o "POR QUE" é absurdamente melhor do que o "O QUE". Na empresa que eu trampo, de vez em quando estou refatorando algo mais antigo e esses comentários de "POR QUE" ajudam demaisss.

Bom, mas ai vale a discussão de, a documentação dos porques deveria estar dentro do código? O código não deveria ser apenas o como? Uma documentação técnica ou um README bem escrito não seria uma prática melhor? Eu sou da turma que acha que comentários ou atrapalham (se você confia neles) ou são inúteis porque nem são lidos (meu caso).

Prefiro mil vezes uma função chamada "transfere_cliente_para_fila" do que um metodo "transfere" com um comentário.

Sério, muito importante isso decumente o porque, faz muita diferença na hora de dar manutenção. Fora que o código tem que ser bom viu, se não, não adianta comentar nada.

Acho primordial escrever codigo limpo e enxuto, mas comentarios são essenciais. Porque em muitos casos o código pode ficar complexo e só praticas clena code nao adiantam.
Eu já escrevi um comentario assim uma vez:
"// quando escrevi esse codigo apenas eu e Deus sabia como funcionava, agora só Deus."

Na minha visão você deve tanto documentar "o que" e o "por que".
Claro que o "por que" é muitas vezes mais necessário, mas nem sempre o "o que" é claro de entender apenas olhando o código.

Você pode dizer também que basta limpar o código que o "o que" vai ficar mais claro, mas no mundo real isso nem sempre é viável.
Tem certas coisas que se você limpar demais vai deixar menos flexíveis, mais ruins de manter etc.

Tá aqui um exemplo que estava mexendo agora pouco:
ele nem diz o "por que", porque nesse contexto é meio óbvio, mas o comentário diz o "o que", porque não é algo fácil de notar instantaneamente.

// NewPeerConn stablishes a TCP connection followed by a BitTorrent handshake.
func NewPeerConn(peer Peer, myHs *Handshake) (*PeerConn, error) {
	conn, err := net.DialTimeout("tcp", peer.Address(), 3*time.Second)
	if err != nil {
		return nil, err
	}

	defer conn.SetDeadline(time.Time{})

	conn.SetDeadline(time.Now().Add(5 * time.Second))
	_, err = conn.Write(myHs.Bytes())
	if err != nil {
		return nil, err
	}

	hsBytes := make([]byte, 68)
	_, err = conn.Read(hsBytes)
	if err != nil {
		return nil, err
	}

	conn.SetDeadline(time.Now().Add(5 * time.Second))
	yourHs, err := HandshakeFrom(hsBytes)
	if err != nil {
		return nil, err
	}

	if yourHs.InfoHash != myHs.InfoHash {
		return nil, fmt.Errorf("infoHash do not match. want: %x, got: %x", myHs.InfoHash, yourHs.InfoHash)
	}

	return &PeerConn{
		buf:  make([]byte, 4096),
		peer: peer,
		conn: conn,
		busy: atomic.Bool{},
	}, nil
}

Como iniciante em programação, sinto que fui um pouco induzido a acreditar no mito de que o bom código tem de ter muitos comentários. Até faz certo sentido nas etapas elementares do aprendizado em programação, mas pode se tornar uma muleta.
Hoje, somando minha (pequena) experiência às reflexões compartilhadas aqui, acredito que pode ser mais uma ferramenta, um guia, no processo de melhoramento do código. As partes excessivamente comentadas se tornam pontos de revisão, indicando que a lógica ali pode ser melhorada mais tarde. O próprio habito de pensar nos comentários - e sua necessidade (ou não) - pode ser um bom ponto de reflexão e condutor do processo de escrita.

acredito que se o código está dificil de entender, deixar comentários é uma boa, ou pra casos como um código que outra pessoa deixou lá e está ruim, vale a pena ir colocando comentários para se orientar enquanto lê e para deixar para outras pessoas que eventualmente tenham que mexer nesse código

Cara seguindo as boas praticas comentar código é uma má pratica a não ser que ele seja necessario, basicamente você vai comentar um código que alguem não vai entender o que faz só de olhar, ou seja, se você esta comentando seu codigo é porque ele esta sujo. Possa ser que eu esteja sendo ignorante ou apenas seguidor fiel do clean code mas cara faz sentido. Pensa se teu codigo não estará legivel pros outros só pra ti, quando alguem precisar fazer uma manutenção ali as vezes mesmo com teu comentario pode ser dificil saber onde mexer no codigo entende? Coisas como SOLID, TDD, testes unitarios de integração etc, podem parecer até inuteis mas são valioso na hora de codar.

Gostaria só de falar sobre essa parte de documentação, recentemente eu vi algo que faz sentido: Testes únitarios servem de documentação de programador para programador. Obviamente que isso não isenta de fazer a parte de documentação real do código, mas testes únitarios são boas praticas que te economizam tempo no futuro sabe. Enfim.

Gostei do tema levantado. Eu nunca havia pensando no lado do POR QUE.
Auxiliando a dar um grau de estabilidade para o código, com a prevenção de alguém olhar algo que, a primeira vista não faria sentido estar ali, no entanto há um pensamento por trás.
Começarei a incorporar a prática no meu dia-a-dia.