Todas as outras respostas e comentários aqui realmente me deram uma chance, porque eles são tão contrários à minha primeira reação e tão contrários à atitude que eu testemunhei em meus colegas de trabalho. Então, eu gostaria de descrever uma abordagem alternativa, mesmo que apenas por uma questão de ser dissidentes voz.
O princípio orientador desta resposta é "Encantar o cliente". Encantar o cliente não significa apenas atender às suas expectativas; significa compreender tão profundamente seus pedidos que você pode interpretar o que eles dizem da maneira que eles querem dizer, e entregar acima e além do que eles pedem. Outras respostas parecem ser guiadas pelo princípio da conformidade maliciosa, que eu considero repugnante; e, além disso, é uma prática empresarial questionável, pois é uma maneira ruim de obter clientes fiéis.
Para mim, quando ouço o cliente dizer "quero 25% de comentários", esse é o começo de um diálogo. Para mim está claro que a implicação aqui é "Eu quero um monte de texto descritivo, para que os recém-chegados a esta base de código pode se levantar e correr rapidamente", e não "eu quero que você adicionar aleatoriedade em uma determinada categoria sintática" como outras respostas parece estar tomando isso. E eu gostaria de que ter pedido a sério, e pretende escrever um monte de descritivos, comentários úteis, guiando um recém-chegado a estrutura do código, apontando decisões de engenharia surpreendentes e delineando o raciocínio que foi para eles, e dando de alto nível Inglês descrições de seções de código complicadas (mesmo que elas não tenham surpresas). Essa intenção e compreensão é o ponto de partida da discussão - isto é, antes mesmo de começarmos a falar. Para mim, a implicação do pedido é tão clara que nem precisa desse esclarecimento; mas se para você não está claro, você deve, é claro, checar com eles!
Ok, então onde é que o diálogo vai, se esse é o ponto de partida? A próxima parte da caixa de diálogo é assim:
- Eu esperaria que isso fosse um esforço adicional sério, possivelmente em uma segunda fase do projeto, que está acima e além da produção da ferramenta que eles se preocupam em trabalhar. Podem ser vários minutos de discussão para discutir este processo e por que é um trabalho adicional, mas vou omiti-lo aqui porque, como programador profissional, espero que você saiba como é difícil ser bom comentários.
- "Um esforço adicional sério" significa que podemos precisar de um orçamento mais longo e de um orçamento monetário maior; ou podemos precisar reduzir o orçamento de recursos; ou podemos precisar comprometer a qualidade e a quantidade de comentários. Esta parte vai ser um pouco de negociação. Mas, na minha opinião, você deve ser muito franco sobre os custos de fazer esse trabalho extra e certificar-se de que é uma característica tão importante para o cliente que eles estão dispostos a assumir esses custos. E se eles são - ótimo! Você ganha mais tempo e dinheiro e recebe comentários de alta qualidade. Todo mundo ganha. E se se verificar que o recurso comentando não é tão importante para eles que eles estão dispostos a perder a capacidade de flurgle Widgets ou disposto a deixar o deslizamento prazo até o final de Granuary, 20X6, então todo mundo ganha novamente: eles obter o produto que quer, e você não precisa gastar o esforço extra necessário para criar comentários de alta qualidade.
Aqui é onde eu acho que o diálogo deve não ir:
- Não ameace o cliente com comentários de baixa qualidade. Deixe-os ajudá-lo a escolher o nível de esforço que desejam e que estão dispostos a pagar. Não prometa a eles 25% de comentários e, em seguida, informe-os de que você pretende cumprir essa promessa automatizando a aleatoriedade após a construção do projeto.
- Não esconda seus planos. Não prometa a eles 25% de comentários e, em seguida, gerencie automaticamente a aleatoriedade sem dizer a eles que é isso que você vai fazer. Quando eles percebem (não se), vocês dois perdem tempo: eles estão insatisfeitos com o produto que receberam, e você tem um boca-a-boca negativo.
- Não tente convencê-los de que eles não querem comentários. Eles claramente querem comentários. Discuta tradeoffs de várias abordagens: sim! Discuta formas alternativas de tornar amigável o novato da base de código: sim! Diga-lhes que eles não sabem o que querem: eh, não. Você quer trabalhar com eles para conseguir o que eles querem; então, entenda o que é isso e descubra a melhor forma de entregar isso a eles com um orçamento aprovado, priorizando os recursos com os quais mais se preocupam se os recursos que possuem forem insuficientes.
- Não crie desculpas sobre o quão difícil é escrever os comentários. Escrever código é difícil; o código de depuração é difícil; Escrever comentários é difícil. Se fosse fácil, eles não estariam contratando você. Basta pular as reclamações e ir direto ao ponto com o qual elas se preocupam, ou seja, como o esforço extra necessário as afeta.