Forçando as pessoas a ler e entender o código em vez de usar comentários, sumários de funções e depuradores? [duplicado]

O código bem escrito deve ser suficientemente auto-documentado para que você não precise de nenhum comentário explicando o que o código faz, porque é óbvio pela leitura do próprio código. Isso implica também que todas as funções e variáveis têm nomes descritivos, embora possam ser necessárias para aprender a linguagem dos domínios do problema e da solução.

Isso não significa que o código bem escrito deve ser completamente sem comentários, porque os comentários importantes são aqueles explicando por que uma função / bloco / etc particular não-trivial é implementada como é e porque não foi escolhida uma solução diferente?

O problema com comentários descrevendo o código em si é que eles tendem a ficar desatualizados, porque o código é alterado para corrigir um bug, mas os comentários permanecem inalterados. Este é muito menos o caso com comentários descrevendo o raciocínio para chegar à solução atual.

Alguém (atribuído a Richard C. Haven , um programador Delphi) escreveu uma vez:

• Iniciantes não comentam nada.

• Os Journeymen comentam o óbvio.

  myVar = myVar + 1; // add one to myVar
  
  /* This method adjusts the page margin by the appropriate device offset */
  

• Os mestres comentam o motivo de não fazer isso de outra maneira

  /*
  
  I already tried obvious approaches A, B, and C to solve this problem.
  They didn't work for the following reasons: ...
  
  Therefore I wrote this less-than-obvious approach which works and 
  passes all unit tests.  
  
  */
  

Seu "programador sênior" pode ser sênior em termos de idade / longevidade, mas parece-me que ele tem algum crescimento profissional para fazer.

Quanto à depuração, há muito a ser dito sobre código limpo e uso liberal de log e / ou print() . No entanto, usando um bom depurador, geralmente consigo encontrar o problema em uma pequena fração do tempo que levaria sem ele. É uma ferramenta elétrica. Use-o.

I want to force people to read the code. I hate debuggers for a similar reason. They are too convenient and allow you to step through dirty code with watches and breakpoints and find the so-called problem, when the real problem was that there are bugs in the code because the code has not been simplified enough.

Seu programador sênior parece ter um problema compreensível sobre o estilo de codificação . Ele está errado em como ele resolve o problema, no entanto.

Ambos comentários e codificação descritiva são essenciais: código bem escrito com nomes descritivos informa rapidamente o código ; mas os comentários informam o que o código deve fazer (e por que não, por que ele faz isso de uma forma e não de outra . Então você tem testes de unidade para verificar se o "contrato "(o que o código deveria ter feito ) foi realmente cumprido e feito automaticamente, com frequência e sem nenhum esforço adicional da sua parte.

Sem os comentários, levaria muito tempo (ou um teste de unidade, que neste momento eu suspeito que seu chefe goste menos do que os comentários, se ele acreditar que " bugs foram pegos por pessoas lendo código ) antes de encontrar o erro:

// Multiply margin by a fixed amount.
page->margin += fixedMargin;

e, sim, o comentário pode estar errado, mas agora você sabe que em uma dessas duas linhas há um erro . Isso, além de outro recurso útil, controle de versão , permite que você encontre a discrepância em menos de 30 segundos. Verificar a saída e até mesmo avançar com um depurador pode não ser (um valor de fixedMargin de cerca de 1.01 pode fornecer resultados ambíguos, por exemplo).

Se o seu mentor está atrás da simplicidade (eu concordo com ele que é um traço desejável), ele deve implementar alguma maneira de verificar métricas como e estabelecimento de metas métricas. Isso vale para comentários também: eu concordo que não faz sentido documentar cada linha de código, mas você deve se esforçar para cobrir módulos, funções e qualquer "ponto WTF" no código.

// Useless comment: multiply a by four

// Useful comment (even if maybe it shouldn't be in this exact point of code):
// Zooming 2:1, four pixels get mapped into one, divisor needs multiplying by four
a *= 4;

Seu mentor aparentemente está confortável com uma quantia espantosa de dívida técnica . Eu verificaria as estatísticas dele sobre o escorregamento de prazo e / ou ETAs; a menos que um milagre, qualquer projeto de longa duração que não seja mantido por uma banda de um homem só ou por um grupo de colegas de codificação é devido a uma dívida técnica chamada mais cedo ou mais tarde.

Se você puder apenas "ler o código", você não terá uma idéia do que a função pretende fazer . Então, se alguém fode (eu sei que ninguém faz, este é um caso hipotético) e faz algo errado, você não tem como verificar isso no código. Você tem que esperar por testes de unidade para detectá-lo (se eles verificarem).

Acrescente a isso, que não adicionar comentários me obriga a ler as funções A1, A2, A3 ... do começo ao fim, enquanto estou interessado apenas em entender a função A, que chama todas as opções acima.

Eu apostaria em seu programador sênior ser preguiçoso (ruim) ou querer que as pessoas percebam o quão inteligentemente ele codifica (bem pior).

If you put in comments, people won't read the code as much. Then bugs don't get caught, and people don't understand the quirks, bottlenecks, etc. of the system. That's provided the comments are actually updated with code changes, which is of course totally unguaranteed.

Nada como um idiota opinativo.

Na próxima vez que for comprar um livro para ler. Certifique-se de lê-lo de capa a capa antes de comprá-lo. Caso contrário, você nunca saberá exatamente se é o que você está procurando comprar. Isso é basicamente o que ele está dizendo para você fazer.

Ele fez algumas suposições que são tolas.

1. A leitura do código-fonte fornecerá a perspectiva purista do que ele faz.
2. Os comentários pertencem ao scope do código-fonte ao qual estão associados.

Essa é sua perspectiva restrita sobre comentários e, como tal, ele não vê valor neles. Aqui estão as limitações de não ter comentários.

1. O código-fonte é um conjunto de instruções para um computador. Não expressa conceitos ou idéias. Portanto, o código-fonte nunca lhe dirá quais foram os objetivos dos programadores. Código-fonte que compila sem erros e não falha, ainda pode falhar em atingir os objetivos. Como você saberá diferente do computador lendo o código-fonte? O computador já faz isso, mas ainda pode falhar em atingir o objetivo.
2. O código-fonte não explica a intenção do programador. open window, prompt for deposit não explica que o programador pretendia comunicar um aviso ao usuário.

Na próxima vez que você tiver uma conversa com esse cara, ele perguntará por que você está adicionando comentários ao seu código-fonte. Responder com esta afirmação.

"I write source code to tell the computer what to do, and I write comments to tell people what to do."

Os comentários devem ser usados como um registro escrito que explica algo confuso. Se você está escrevendo algo que é potencialmente confuso e não pode ser simplificado, de tal forma que você suspeita que até mesmo você terá dificuldade em entendê-lo seis meses depois, então escreva um comentário.

Se você comentar liberalmente, em tudo e em todos os lugares, os comentários perdem sua eficácia ao sinalizar as dificuldades. (Rememer a fábula do menino que gritou "Wolf!")

Os comentários ocupam o "espaço real da tela", a menos que você tenha um bom editor de dobras; você tem que ficar pulando por eles quando se movimentar no código. E, é claro, comentários como /* increment i by one */ ao lado de i++ são lixo completo.

Se o código é tão complicado que requer um guia para os internos, então, por gentileza, escreva um guia para os internos. Chame README-internals.txt (ou talvez HTML) e coloque-o no mesmo diretório que o código e coloque um comentário que diga /* this is all explained in README-internals.txt */ .

Sobre os depuradores: qualquer ferramenta que ajude a encontrar um bug é valiosa. É tolice dispensar ferramentas. Os depuradores de ponto de interrupção não devem ser usados para verificar se o código está funcionando. Pelo menos, não invocado como um meio primário. Um depurador passará alegremente por uma instrução como a[i] = i++ em C e confirmará uma má intuição.

Ferramentas de depuração que realmente capturam algum tipo de violação de tempo de execução, no entanto, podem ser consideradas como uma ferramenta de teste. Se você tiver um depurador que detecte erros de uso da memória dinâmica e o código passar por vários casos de teste nesse depurador, isso é uma fonte de confiança de que a memória não está sendo usada incorretamente.

Portanto, lembre-se de que "depurador" se refere a mais de um tipo de ferramenta, não apenas a um depurador de ponto de interrupção / etapa. Alguns depuradores fornecem apenas uma visão do programa, deixando você fazer o raciocínio sobre o que está errado, enquanto outros depuradores procuram por problemas para você.

O código nem sempre pode ser simplificado para não ter um depurador ou se recusar a usá-lo. E se você seguir a sugestão de seu chefe e simplificar o código a ponto de não poder ser mais simplificado, e ainda precisar de um depurador?

Acho que a revisão de código é um processo fantástico para responder a essa pergunta de maneira concreta. Se eu leio o pedido de alguém (fazendo um esforço real para lê-lo, não apenas olhando para ele com a atitude de que tudo deve estar imediatamente aparente) e não entendo o que ele faz, digo às pessoas que adicionem um comentário. Ou você pode fazer isso sozinho com um pato de borracha.

A maioria das pessoas sabe intuitivamente quais idéias precisam ser comentadas - é o que você diria a alguém que está ao seu lado se ele fizer uma pergunta sobre o código. Muitas vezes peço a alguém para explicar algo em uma resenha, eles dão uma ótima resposta, e minha resposta é "Copie essa explicação que você acabou de escrever em um comentário no código".

Mas, por alguma razão, esse raramente é o conteúdo que as pessoas acabam escrevendo em seus comentários. Em vez disso, as pessoas escrevem coisas fúteis como

/**
 * Gets the {@link List} of {@link Author}s for the given {@link Book}.
 *
 * @param book The {@link Book} for which you want the {@link Author}s.
 * @return All of the {@link Author}s for the given {@link Book}.
 */
List<Author> getAuthors(Book book) { ...

e

// increment i by 1
i += 1

e esse é o tipo de coisa que os colegas experientes estão reagindo. Eu mesmo digo às pessoas quando estou revisando código para remover esses tipos de comentários de baixo nível que não adicionam mais informações do que as encontradas nas linhas imediatamente ao redor.

Um bom exemplo de uma coisa trivial que faz precisa ser comentada é a descrição dos tipos de pato em linguagens dinâmicas. Se o argumento ou valor de retorno de uma função for um dict com várias propriedades nela, você terá insanidade mais tarde se não comentar exatamente quais são essas propriedades.

Nenhuma quantidade de comentários aumentará qualquer código não trivial para o nível que uma pessoa de 8 anos de idade possa entender, então você não deve tentar. Você tem que fazer algumas suposições que o leitor saiba como ler o código, porque senão é um esforço completamente fútil.

Finalmente, os comentários estão muito errados. As pessoas costumam ignorá-las durante a leitura e não as atualizam quando as coisas mudam. Você não pode escrever um teste de unidade para seus comentários, então apenas a maneira de defender seu código contra a podridão que ocorre quando seus colegas de trabalho descuidados começam a brincar com ele é apenas comentar se as idéias são essenciais. Comentários que não agregam valor adicionam valor negativo quando se tornam errados.

Design de documentos, ideias, arquitetura, história, lógica - não linhas de código.

Em um mundo perfeito, sem prazos, sua abordagem pode funcionar.

A user reported a bug in application X. We'll let the new guy spend two months to get a deep and thorough understanding of the code, and then maybe add a few weeks of refactoring. If the bug still occurs, he should be able to find it then and won't even need a debugger!

No mundo real, isso parece ser uma maneira confiável de sair do negócio.

Exemplo de comentário ruim

foo(); //calling function foo

Bom comentário

foo(); // must call function foo, because of a bug {link to bug}

O Code Complete, o trabalho seminal no estilo de codificação, dedica várias seções (começando com 19.3 na edição 1) à questão dos comentários: o bom, o ruim e o feio. Então você e seu desenvolvedor sênior provavelmente devem dar uma olhada lá.

Dito isto, comentários bem escritos e bem colocados são muito importantes para qualquer projeto de larga escala / longo prazo.

Em um mundo perfeito, é verdade que os comentários não seriam importantes . Mas, a menos que você tenha uma memória fotográfica e todos que trabalham em seu código sejam geniais, bons comentários apenas ajudarão a entender o código muito mais rápido quando você precisar voltar um ou dois anos depois e modificá-lo, ou outra pessoa herda seu código. (Estou dizendo que isso funcionou profissionalmente por 20 anos, e até 5 ou 7 anos em um projeto com vários outros desenvolvedores envolvidos)

Há alguns anos, herdei um aplicativo complexo que faz o trabalho, mas sofre com uma arquitetura ruim e um estilo de codificação incoerente e inconsistente. Felizmente, o código é bastante bem comentado, o que me poupou dias e semanas de se atualizar com essa base de código.

Outra coisa que me ajudou a acelerar foi o depurador que eu uso. Quando vou analisar um novo software no qual tenho que trabalhar, uma das primeiras coisas que faço é percorrer todos os menus, fazer seleções inválidas ou estranhas e ver se consigo quebrar o aplicativo. Quando eu quebro, eu corro esse cenário com o depurador e vejo onde essa falha me leva. Quase invariavelmente isso me leva a importantes módulos e conjunturas na base de código: uma maneira rápida de encontrar os lugares importantes no mapa.

Embora com meu próprio código eu geralmente não precise usar muito o depurador, há ocasiões em que ele ajuda - ninguém é perfeito, mesmo que eles sejam meticulosos sobre testes unitários (o que geralmente é impossível quando você herdado hermeticamente acoplado código legado.) E se eu usar um novo módulo ou componente, o depurador me ajuda a encontrar rapidamente os erros e mal-entendidos que tenho de lidar para me ajudar a chegar ao ritmo com o material novo.

Resumindo: Tempo é dinheiro e a maioria de nós programa para entregar produtos e pagar as contas . Sentado por semanas a fio passando por centenas de linhas de código para encontrar um bug que o depurador revelaria em 10 segundos, ou um código mal escrito que poderia ser iluminado por alguns bons comentários, não ajudará muito a sua linha de base ....

Seu desenvolvedor sênior aparentemente não está preocupado com a eficiência e prefere que os desenvolvedores passem horas e dias mexendo com código complexo, quando alguns comentários salvam o dia. O mesmo vale para suas idéias sobre depuração. (Apenas curioso: o desenvolvedor sênior usa um IDE? Por que não basta digitar tudo em um arquivo de texto e fazer uma compilação e link a partir da linha de comando, etc? Qual a melhor maneira de entender cada linha de código ...)

The comments don't say anything other than what the guy thought the code does at the time he put in the comment

Você sabe, é uma abordagem extremamente teórica. Eu não ficaria surpreso, se fosse dito por matemáticos teóricos, mas em sons de desenvolvedor sênior não soa como se fosse alguém com uma prática realmente longa.

Bem, teoricamente, você pode analisar o código na cabeça, mas funciona apenas com programas muito simples. Com os mais complexos e reais, você se depara com o Problema de parada , que é um dos problemas mais complexos da teoria da computação. Se alguém diz que pode analisar programas na cabeça, ele provavelmente pode fazer a descriptografia RSA na memória:)

Parece que ou o seu desenvolvedor sênior não tem experiência real com problemas complexos ou está tentando impressioná-lo com truques tirados do filme Hackers , ou ele quer justificar seu próprio preguiça quando se trata de escrever comentários.

Os comentários são para quem , quando , porque , pressupostos , dependancies e possivelmente como .

Quem escreveu isso? Quem eu vou e bug se tenho dúvidas sobre isso?

Quando eles escreveram?

Por que eles escreveram? Qual foi a razão da empresa que eles gastaram tempo escrevendo código?

Por que eles escolheram essa abordagem e que outras abordagens rejeitaram e por quê?

Quais suposições eles fizeram? Quais crenças sobre a organização eles mantinham?

Quais são as coisas necessárias para que esse código seja executado com sucesso? Quais bibliotecas, objetos, ambientes ou outras coisas dependem?

Quais são as situações em que o código pode falhar e como o código lida com essas falhas? Como eu lido com eles?

Quanto ao "como", os comentários só devem explicar como o código funciona se for complicado e difícil de entender (e, se for esse o caso, talvez o programador tenha se esforçado mais para simplificá-lo).

O que seu desenvolvedor sênior está se referindo é a entropia de código. Imagino que ele esteja se referindo a casos em que o código é mal projetado e a única maneira de compreendê-lo bem e trabalhar com ele são os comentários e o depurador.

Em outras palavras, comentários e depuradores podem ser usados para solucionar problemas subjacentes. No entanto, eles são ferramentas e culpar a ferramenta não é uma maneira eficaz de fazer qualquer coisa.

Para o seu exemplo, se uma base de código tem muitos códigos quebrados, a solução é não deixar de fora os comentários e fazer com que todos leiam o máximo de código possível. Na verdade, isso é um desperdício de tempo e recursos. Em vez disso, configure processos como revisão por pares e programação em pares, em que o código escrito por uma pessoa certamente terá sido revisado por outro. Esses processos não apenas atingem o mesmo objetivo com melhor precisão, mas também evitam o desperdício de recursos, onde dezenas de desenvolvedores precisam entender um pedaço complexo de código, apenas porque falta comentários e documentação.

Além disso, comentários eficientes podem reduzir a quantidade de erros no código. Lê-los torna o código-fonte mais fácil de entender e, muitas vezes, evita que você tenha que pesquisar por lotes inteiros de arquivos de origem, apenas para descobrir por que uma linha de código é necessária. Claro, o comentário pode acabar errado - mas a menos que a qualidade geral do projeto seja totalmente horrível, você acabará economizando mais tempo confiando em comentários precisos, do que perderá para aqueles que estão desatualizados. E economizou tempo na compreensão, significa mais tempo para a refatoração, que é uma maneira muito melhor de combater a entropia de código.

Estou escrevendo código por cerca de 30 anos e posso ter dito algo muito semelhante ao que disse aquele programador sênior. Também estou muito ciente dos problemas de manutenção.

Ainda acredito que alguns pontos muito importantes foram esquecidos nas respostas acima:

Eu tenho testes de unidade para a maioria do meu código. Você não?

O porquê das funções (a intenção por trás do código) é geralmente expresso através de testes e se os testes por si só não são suficientes, eles são comentados, às vezes muito pesadamente (se alguns de vocês ouviram falar de programação em litterate eles podem entender do que estou falando).

Os comentários opostos no meu código são muito esparsos, quase inexistentes, exceto em dois casos especiais: - se o que é implementado se seguir algumas referências normativas (como implementações de protocolos de rede, no que estou trabalhando atualmente), geralmente coloco a referência como comentário acima do código. - Também uso comentários para evitar interromper o fluxo de programação. Eu insiro comentários como: isto ou aquilo parece errado, conserte depois quando estou codificando algum recurso não relacionado. Estes são comentários de curto prazo (como avisos definidos pelo programador) e devem ser corrigidos posteriormente.

Meu raciocínio sobre fazer isso é que os comentários no código podem ser enganosos. Você pode facilmente ler um comentário e acreditar que o código está executando o que o comentário finge, mesmo que não seja verdade.

Quando os comentários sobre o código estão em testes, as coisas são diferentes. Ele explica como o código deve ser chamado e o teste garante que ele esteja realmente fazendo isso.

Eu geralmente não uso muito depuradores. Eu os mantenho para alguns casos especiais (principalmente quando eu não entendo o que o código faz, como bugs de hardware estranhos).

Isso mudou com o tempo. Há 30 anos, eu usava depuradores intensamente. O que eu observei é que encontrar bugs é geralmente muito mais lento do que outros métodos. O que eu costumo fazer agora é identificar erros em testes de unidade, quanto mais cedo melhor. Isso tem a vantagem adicional de fornecer um teste de não regressão. Nunca mordido duas vezes pelo mesmo erro.

Eu costumava comentar muito, agora muito pouco, tornando o código e os nomes de variáveis legíveis é o caminho a percorrer.
Eu adiciono comentários para 'pegadinhas' reais e 'por que isso foi feito que não é (ainda) óbvio a partir do código'.

Mas para sua pergunta REAL.

Noto que o seu título começa com a palavra: "forçando"

Eu também noto que o primeiro parágrafo menciona "confrontar"

Eu mesmo usei as mesmas palavras há 20 anos:)

Isso (IMHO, é claro) é o que realmente é programação - como diferentes pessoas com diferentes estilos, opiniões, experiência, conhecimento e experiência podem trabalhar juntas.

Não há uma correção simples, nenhuma lista de etapas programáticas a serem realizadas, nenhuma conversa única para definir as coisas corretamente. Eu recomendaria que você pensasse nos seguintes pontos que aprendi com minha experiência de 20 anos.

1. Ouça
2. Ouça
3. Ouça. Desculpem tornar isso um grande problema, mas nada o ajudará mais em sua carreira agora do que fazer perguntas e ouvir, mesmo que a resposta não faça sentido.
4. Faça perguntas e apenas ouça as respostas, mesmo que discorde ou não as compreenda totalmente. Há quase sempre uma segunda chance de revisitar as coisas.
5. Aceite que as coisas sejam feitas às vezes. Se forem realmente decisões ruins que continuarão a aparecer, pode-se fazer um caso mais tarde para torná-las melhores. Mas ênfase no posterior. Bom o suficiente por enquanto é algo que você tem que aceitar às vezes, então você pode saber mais por enquanto.
6. Escolha suas batalhas em coisas erradas. Aprenda a segurar sua língua a menos que o item seja realmente importante para você e, mesmo assim, escolha suas batalhas com muito cuidado - e tente fazer conversas e não batalhas!
7. Aceite as diferenças. Fora da academia, você precisará aceitar mais diferenças e focar um pouco (menos) em encontrar a maneira 'correta e verdadeira' de fazer as coisas e mais no que funciona hoje e nos negócios em que você está trabalhando.
8. Evite conversas em preto e branco. Não seja absolutista sobre a "coisa certa", evite palavras que sejam absolutistas como "deve", "apenas", "impossível" etc., e use palavras como "deveria" "muitas vezes" e "difícil".
9. Use exemplos concretos na conversa, e não na teoria. Não evite a teoria, mas em conversas tente ter exemplos reais para seus pontos. Se você não tem exemplos do mundo real, isso pode ser um indicador de que você deve listar mais do que falar.
10. Enfatize sua juventude e ignorância em conversas com programadores mais experientes, como o que você mencionou. Você irá impressioná-los mais com humildade do que se gabar de seu conhecimento recentemente adquirido.

Os comentários são muito superestimados e usados com mais frequência. Embora eu não saiba da sua situação atual (já que não acho que a citação citada exija uma boa legibilidade do código), em geral você não deve espalhar comentários por todo o código (talvez com exceção dos comentários de alto nível, que são já perto de documentação0.

É por uma razão que comentar é um dos cheiros de código descritos no livro de Martin Fowlers Refactoring (para um resumo, veja: link , o livro não está disponível gratuitamente afaik).

No entanto, você deve substituir comentários por nomes de variáveis e métodos significativos, e não acho que w e gs classifiquem. No entanto, pessoalmente, gostaria de pressionar mais sobre a boa nomenclatura do que sobre os comentários.

Btw, se você pesquisar por 'código limpo' e 'comentários' ou 'código de cheiro' e 'comentários', você encontrará ótimas leituras sobre isso, por exemplo. link (com um resumo de por que o tio Bob Martin, da Clean Code, não gosta de comentários)

Toda vez que você escreve um código, você deve estar pensando no próximo programador que herdará o que você escreveu. Se você escrever comentários porque foi ensinado a fazer isso como uma prática recomendada ou apenas por hábito, provavelmente deveria parar de escrever comentários o tempo todo, porque qualquer pessoa que esteja lendo suas coisas começará a ignorá-los como inúteis.

Se você só comentar quando as convenções de nomenclatura e estrutura não puderem explicar algum elemento estranho do que você está fazendo (geralmente por causa de algo em uma base de código que seja completamente falsa), eles vão perceber isso. Se você está marcando pedaços problemáticos de código, para chorar, coloque uma data nele para que seja mais fácil revisar as mudanças que levaram às travessuras no controle de origem.

Dito isto, não trocaria as ferramentas do Chrome Dev ou o Firebug por nada menos do que uma caixa policial de viagem no tempo. Mas o ponto, penso eu, é isto. Se a primeira coisa que você fizer for iniciar um rastreio no depurador sem ao menos observar o código envolvido, talvez você não esteja estruturando seu código da melhor maneira possível. Sempre se esforce para ser tão direto e óbvio e minimalista e fácil de ler como se não houvesse IDE ou depurador para ajudá-lo. Comece olhando para o seu código quando você atingir um obstáculo primeiro. Se não é fácil adivinhar onde as coisas estão indo mal, você pode pensar um pouco mais sobre como escrever código sem ferramentas modernas. A maioria dos Java e C # que eu já vi é sem noção sobre os fundamentos básicos da OOP.

Os comentários no código são uma dádiva de Deus quando usados corretamente, mas como outros aqui apontaram, eles são freqüentemente usados em demasia. Eu não vou reiterar o que já foi apontado, mas vou dizer que você só deve comentar se você sabe que o código que você está escrevendo é complicado e não há outro caminho viável.

Se você sentir que precisa comentar, pense primeiro no código e pergunte a si mesmo; Por que você está escrevendo esse comentário? Existe outra maneira de escrever o código que não precisaria de um comentário?

Não escreva comentários para escrever comentários. Comente apenas como último recurso ou onde ajudará aqueles que terão que trabalhar no código mais adiante. Se você se encontrar escrevendo comentários descrevendo o que uma variável está fazendo, então é provável que você esteja comentando demais. Programadores ruins comentam tudo, bons programadores comentam apenas quando necessário.

Sobre o assunto dos depuradores, eu trabalho com alguns engenheiros que passaram toda a sua carreira sem nunca disparar um depurador. Por quê? Um depurador é uma ferramenta como qualquer outra. Assim como na maioria dos casos, um martelo de bola faz o trabalho, às vezes você precisa de algo com mais finesse.

Um depurador serve a dois propósitos.

1. É usado para encontrar erros
2. Mostra um caminho pelo seu código.

Eles podem ser muito úteis para trazer os novatos até a velocidade e podem ser ainda mais úteis para rastrear os mais difíceis de encontrar bugs, mas eles não são o único caminho e há momentos em que um depurador é realmente um impedimento ajuda.

Quanto ao resumo de funções, bem, todas as funções devem ter um bloco de documentação, isso é obrigatório, mas não as torne longas e elaboradas. O verão deve ser uma descrição de 1 linha com cada parâmetro claramente descrito.

/**
 * A getter method for foo
 *
 * @param bool $bar If true, bar will be attached to foo
 *
 * @return foo
 */

Use somente um bloco de documentos detalhado se houver motivo para isso. Se o método é muito complicado, então sim, coloque uma explicação, mas, sempre que possível, tente evitá-lo. Um bom código deve documentar-se.

Lembre-se, todo mundo gosta de ler romances, mas ninguém quer ler guerra e paz às 9h da manhã de segunda-feira.

Os comentários são muito úteis e podem ser a diferença entre o código limpo e o código não claro.

Só porque foi feito de uma maneira "no passado" não significa que outra maneira seja inaceitável.