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.

Eu não sei você, mas toda vez que eu vou usar uma função numa linguagem eu leio a "doc" dela pelo próprio VSCode, e na maioria das vezes essa doc nada mais é que um comentário em cima da função.

Acho útil demais, porque eu consigo ver instantaneamente os detalhes de uma função sem precisar trocar de programa.

https://i.imgur.com/Ha0djbm.png

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 s...