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.

jeffersondrshá 2 anos

Neste caso, o nome da função que chama essas variáveis, ou até mesmo o nome do array/objeto deve ser escrito de forma a dar a entender de onde vem as variáveis. exemplo: const fraccionalPartsCubeRoots = [...]. Claro, que dei apenas um exemplo de como se pode salvar a variável e chamar ela de forma intuitiva, o código limpo deixa isso claro, mas quem escreve o código deve se preocupar com seu entendimento futuro, caso contrário, será uma pilha desnecessária de comentários, onde deveria somente ao ler o código, entender o que cada fração faz. Concordo que comentários devem ser ao máximo evitados, e se tiver escrevendo um código limpo, será totalmente dispensável. De outra forma, não está sendo limpo.