Meu cliente quer 25% de comentários no meu projeto atual, como reagir? [fechadas]

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:

1. 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.
2. "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:

3. 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.
4. 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.
5. 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.
6. 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.

O cliente é rei. Então, como empreiteiro, você deve atender o que o cliente definiu como padrão de qualidade. Ou você arrisca estar fora.

Dito isto, importa muito como os padrões de qualidade (aqui pobres) são definidos:

• Padrões contratuais de qualidade: o código fornecido deve estar de acordo ou, de outra forma, é uma quebra de contrato. Nenhuma escolha

• Padrões de qualidade corporativos formais: mesmo que funcione perfeitamente, o código que não obedece será considerado de má qualidade por tantas pessoas, que você ficará velho antes de convertê-los todos em uma prática melhor. Pior: ferramentas conhecidas podem ser usadas para automatizar e legitimar essas métricas de qualidade (por exemplo, cubo de sonar ). Quase sem escolha.

• Critérios ad-hoc definidos por algumas pessoas no cliente. Aqui você pode envolver discussões. Há esperança :-)

Neste último caso, poderia haver alguma flexibilidade, e você poderia tentar enfatizar diplomaticamente o ponto. Aqui alguns argumentos que falam contra os critérios do cliente:

• Problema de produtividade: a codificação é feita duas vezes (uma vez em inglês e uma vez no código).
• Problema de precisão: se forem feitas alterações no código, elas devem ser feitas nos comentários ou os comentários podem se tornar inúteis.
• Problema de refatoração: como a ferramenta de refatoração não processa os nomes das variáveis nos comentários.
• Questão de risco: a ambiguidade (ou obsolescência) dos comentários pode gerar confusão e risco para aumentar os erros.
• A quantidade não é de qualidade
• Esta divertida coleção de comentários inúteis no StackOverflow .
• Este artigo que argumenta que uma alta taxa de comentários poderia até mesmo seja o sinal de um cheiro de código.

Mas em vez de falar contra o mal e confrontar o cliente, você pode simplesmente promover melhores abordagens:

• Código de limpeza (sugira o livro ao seu cliente: há uma seção convincente dedicada a comentários e código de autodocumentação).
• Prática de documentação: As coisas mais difíceis de compreender e, portanto, as informações mais valiosas, como por exemplo a relação e interação entre classes, são melhor documentadas em um documento separado (por exemplo, em uma imagem UML em vez de 1000 palavras de comentário? )

Se o cliente ainda não está convencido, você poderia propor uma alternativa experimental, usando ferramentas gerar automaticamente documentação com comentários, como javadoc ou doxygen . Proponha com isso mudar o foco da quantidade (25% do código) para a qualidade (gerar um javadoc compreensível).

The client wants at least 25% of comments in each of its software projects.

O cliente realmente quer 25% de comentários ou o seu cliente quer que seu código seja o mais descritivo possível?

IMHO, o cliente sabe o que ele quer, mas não o que ele precisa. Como um cliente não é um desenvolvedor em si e recebe feedback de seus próprios funcionários / clientes, seu cliente só vê a parte superior do iceberg.

Eu acho que seu cliente tem algum pseudo-conhecimento e quer que o código seja bem documentado e de fácil manutenção, e a ferramenta para isso são comentários (em sua mente).

Tente falar com ele e preparar alguns trechos de código com um código bem escrito que explique a si mesmo, e outro código ruim com comentários. Apenas algumas linhas. Mostre isso, se necessário, e use-o como figura para suas palavras.

Converse com seu cliente / supervisor / qualquer coisa e tente dizer a eles os princípios modernos de controle de versão (sem necessidade de comentários no início do arquivo) e código limpo (recomendo o livro também, e assim resultando código auto explicativo.

Talvez, se você mostrar bem o suficiente e fazer com que seu cliente entenda que ele quer código limpo, não apenas comentários, você e sua equipe podem escrever um código melhor (com muito menos comentários) e mostrar imediatamente que você é um bom desenvolvedor vale a pena manter.

Isso me lembra daquelas respostas tolas do Stack Overflow que você vê que consistem em uma linha seguida por, literalmente, "algum texto aqui para chegar ao limite mínimo de caracteres".

Quando isso acontece, pode-se argumentar que dois grupos de pessoas estão em falta:

1. As pessoas que colocam o limite - claramente é excessivo e impede que as pessoas enviem suas informações adequadamente formadas sem adicionar ruído artificial

2. As pessoas que enviaram informações que não foram foram formadas corretamente e adicionaram ruído artificial quando o sistema solicitou que adicionassem mais substâncias reais

Por vezes, uma questão será simples e no tópico, e não há muito mais a dizer do que algumas palavras. No entanto, isso é extremamente raro. Em quase todos os casos, há muito mais substância para dizer. Se nada mais, deve ser cegamente óbvio que a maneira de contornar uma restrição de personagem não é apenas descarregar ruído aleatório em sua postagem.

Esta situação de comentários que você está enfrentando é quase a mesma. Seus desenvolvedores aceitaram um pedido de comentários e implementaram-no, descarregando ruídos aleatórios em seus códigos. Documentar os nomes das variáveis, ao lado da declaração das variáveis, é vandalismo . Isso nunca deveria ter acontecido.

"Mas de que outra forma podemos chegar a 25%?" Escrevendo comentários reais de substância. Use mais palavras, melhores palavras, as melhores palavras para documentar o efeito das funções. Expanda suas explicações. Descreva os casos de borda em mais detalhes.

No entanto, voltando ao ponto original, o cliente também está parcialmente em falta, porque "25% do código-fonte" é extremamente arbitrário. Em última análise, porém, eles são o cliente, então faça o melhor possível. Mas eu quero dizer "melhor". Não "pior", como tem acontecido até agora.

Eu não sei qual é o grande problema com este requisito.

Apenas pela doxigenação básica do seu código, você provavelmente já está com 10% ou mais. E vamos dar mais 5% dos comentários que você escreveu para si mesmos (alguns escrevem mais, mas 5% parece uma estimativa conservadora se você não tiver feito um voto de silêncio). Neste ponto, é em torno de 15% (sim, sim, eu sei, 5% de 90% é menos que 5%, não use nitpick). Se o seu doxygen é menor que 10%, talvez seus métodos sejam muito longos; geralmente é uma boa ideia dividi-los em pequenos (principalmente privados / protegidos) ou usar mais classes auxiliares genéricas, etc.

Agora, para o restante do texto do comentário, coloque considerações de design e cenários de uso em comentários no nível da classe / arquivo. Tem algumas tabelas ou ASCII-art (ou código doxygen que gera coisas mais agradáveis quando são renderizadas). Eu não sei, é claro, sobre o que é seu projeto, mas acredito que você pode fazer isso sem comentários falsos (além do boilerplate de doxigenação) e chegar a algo próximo de 25%.

Se for apenas, digamos, 20% e não 25% - tenho certeza de que o cliente apenas forneceu esse número como algo arbitrário e ficará bem com ele. De qualquer forma, converse com eles para discutir o que os comentários devem abranger; e mostre-lhes um exemplo de arquivo comentado para ver se estão satisfeitos. Se eles são, então é isso, se eles acham que algo está faltando, eles lhe dirão o que está faltando. Eles não vão dizer "Não podemos sugerir nenhum comentário extra, mas ainda queremos que você adicione alguns".

PS - Veja o código dos contêineres Java padrão para ver como você pode alcançar, oh, 70% ou mais ...

Ter 25% de comentários em seu código é um excelente objetivo e o cliente fica feliz. Agora, escrever 25% de comentários de preenchimento insignificantes como "i + = 1; // aumentar i por 1" deve estar abaixo de você, então reserve um tempo, escreva comentários úteis e aproveite a sensação de que você é realmente pago para fazer algo que deveria fazer de qualquer forma.

Nós todos sabemos que este é um requisito de porcaria. A questão interessante aqui é

how to react?

Sou um grande crente em tornar os problemas visíveis. Aqui eu usaria o fato de que o dinheiro fala.

Peça-me para fazer isso e direi que adicionará 1% ao meu lance. Ah, mas isso adicionará 20% a qualquer oferta de manutenção futura.

Somente quando perguntarem por que eu ensinarei a eles que o objetivo dos bons nomes é evitar a necessidade de comentar.

Como uma alternativa, vou propor a criação de documentação destinada a obter um programador de manutenção com um conjunto definido de qualificações assumidas para acelerar as idéias por trás do projeto. Ou, claro, eu poderia te dar 25% de comentários. Até você.

Sim, eu entendo sua frustração com a regra boba. Eu li muitos programas com comentários inúteis como

x = x + 1; // add 1 to x

E eu digo para mim mesmo, Então é isso que significa um sinal de mais !! Uau, obrigado por me dizer, eu não sabia disso.

Mas, dito isso, o cliente está pagando a conta. Portanto, você lhes dá o que eles querem. Se eu trabalhasse em uma concessionária de carros e um cliente dissesse que ele queria uma picape, eu não discutiria com ele sobre se ele realmente precisa de uma picape e questioná-lo sobre o que ele espera fazer. Eu venderia uma caminhonete para ele.

Ok, há momentos em que o que os clientes dizem que ele quer e o que ele realmente precisa é tão distante que eu tento discutir o assunto com ele, talvez convencê-lo a concordar com algo mais racional. Às vezes isso funciona, às vezes isso não acontece. No final, se não posso mudar de ideia, dou-lhe o que ele quer. Se ele voltar mais tarde e disser: "Oh, isso realmente não satisfez meus requisitos de negócios, então podemos cobrar mais para ele fazer o que dissemos a ele para fazer pela primeira vez". O quanto você pode negociar com o cliente depende de quanto ele confia na sua experiência, como o contrato com você se encaixa na organização e, francamente, como é que eles são corajosos.

Seria um caso muito raro em que, supondo que dependesse de mim, eu perderia um contrato porque achava que os requisitos estavam mal concebidos.

Tenha em mente que as pessoas com quem sua empresa está negociando podem ou não ser aquelas que inventaram essa regra de 25%. Poderia ser uma regra imposta a eles do mais alto nível.

Eu vejo cinco respostas possíveis:

Um. Convença seu chefe ou quem quer que esteja negociando com o cliente a discutir sobre isso. As probabilidades são de que isso não conseguirá nada, mas você pode tentar.

Dois. Recuse-se a fazê-lo. Isso provavelmente fará com que você seja demitido, ou se a empresa concordar com você, porque você perderá o contrato. Isso parece improdutivo.

Três. Escreva comentários inúteis para preencher o espaço, o tipo de comentário que apenas repete o que está no código e que qualquer programador capaz de modificar o código pode ver em 2 segundos. Eu vi muitos comentários como este. Anos atrás, trabalhei em uma empresa onde precisávamos colocar blocos de comentários na frente de todas as funções que listavam os parâmetros, como:

/*
GetFoo function
Parameters:
  name: String, contains name
  num: int, the number
  add_date: date, the date added
Returns:
  foo code: int
*/
int GetFoo(String name, int num, Date add_date)

A objeção de que tais comentários são um fardo de manutenção porque você precisa mantê-los atualizados não é válida. Não há necessidade de mantê-los atualizados, porque nenhum programador sério jamais os verá. Se houver alguma dúvida sobre isso, certifique-se de deixar claro para todos os membros da equipe que os comentários inúteis e redundantes devem ser ignorados. Se você quiser saber quais são os parâmetros de uma função ou o que uma linha de código faz, leia o código, não examine os comentários inúteis.

Quatro. Se você vai adicionar comentários inúteis e redundantes, talvez valha a pena escrever um programa para gerá-los. Algo de um investimento na frente, mas poderia salvar um monte de digitação na estrada.

Voltar quando eu comecei neste negócio, uma empresa que eu trabalhei para usar um programa que foi anunciado como "Escreve sua documentação para você! Documentação completa para cada programa!" O sistema exigia que dessemos a todas as variáveis essencialmente nomes sem sentido e então tivéssemos uma tabela dando um nome significativo para cada variável, então basicamente o que a "documentação automática" fez foi substituir o nome sem sentido que ela nos obrigou a usar com um nome significativo. Então, por exemplo - isso funcionou com o COBOL - você teria uma linha no seu programa que dizia

MOVE IA010 TO WS124

e eles gerariam uma linha de "documentação" que dizia

COPY CUSTOMER NAME IN INPUT RECORD TO CUSTOMER-NAME IN WORKING STORAGE

De qualquer forma, certamente poderíamos escrever um programa para gerar documentação igualmente sem valor com bastante facilidade. Leia uma linha como

a=b+c

e gere o comentário

// add b to c and save result in a

Etc.

Cinco. Faça o melhor da regra boba. Tente escrever comentários úteis e significativos. Ei, isso poderia ser um bom exercício.

Ah, a propósito, posso acrescentar que você pode sempre jogar a métrica.

Eu me lembro quando um empregador disse que ia começar a medir a produtividade dos programadores com quantas linhas de código produzíamos por semana. Quando nos disseram isso em uma reunião, eu disse: Ótimo! Eu posso facilmente aumentar minha pontuação. Não mais escrevendo

x=x+4;

Em vez disso, escrevo:

x=x+1;
x=x+1;
x=x+1;
x=x+1;

Loops? Esqueça, vou copiar e colar o código dez vezes. Etc.

Então, aqui, se eles contam linhas de comentários, diminua cada linha e continue a ideia na próxima linha. Se houver uma mudança no que acontece nos comentários, não atualize o comentário existente. Coloque uma data, copie todo o texto e escreva "Atualizado" e uma nova data. Se o cliente questiona, diga que você achou necessário manter o histórico. Etc etc.

Métricas arbitrárias parecem ser um fato da vida em muitos projetos ...

Isso é visto frequentemente em requisitos estúpidos, como uma complexidade Cyclomática máxima, que leva a um código mais complexo, porque as funções são desnecessariamente divididas para garantir a conformidade ou os arquivos são divididos porque excedem algum comprimento arbitrário de SLoC

Os comentários devem ser adicionados ao código e explicar o que está acontecendo (e não apenas repetir o código!).

Dito isto, se é isso que o seu cliente quer e a sua empresa concordou em fornecer, a menos que o seu Gestor da QG desenvolva uma dose de bom senso, está preso.

A curto prazo não há nada que você possa realmente fazer. Vá junto com isso.

Você também deve ignorar todas as ideias estúpidas que estou vendo neste tópico sobre protestos passivos agressivos e piadas bobas dentro do código.

Depois de ter desenvolvido uma relação de confiança com o cliente, ele estará em melhor posição para ouvir o seu raciocínio - você pode achar que essa é uma demanda boba de uma pessoa que já foi influente e que tem muito pouco apoio em casa.

Sob nenhuma circunstância você deve ir contra isso sem a permissão do cliente.

Estou desapontado com a falta de imaginação exibida por meus colegas programadores aqui.

Parece-me que o cliente fez alguma pesquisa. Ele pode ter lido em algum lugar que o código de qualidade normalmente contém cerca de 25% dos comentários. Obviamente, ele se preocupa / se preocupa com a manutenção mais abaixo na estrada. Agora, como ele torna isso concreto em um documento de requisitos que deve ser vinculado a um contrato? Isso não é fácil. Pode até ser impossível. No entanto, ele quer ter certeza de que obterá valor pelo seu dinheiro, então ele enumera alguns indicadores de qualidade.

Isso não parece estúpido ou ridículo para mim. As pessoas que escreveram os requisitos provavelmente não são programadores. Eles podem ter tido uma experiência ruim com um projeto anterior. Seus caras de manutenção estão reclamando: "Nenhuma dessas merdas está documentada!". Está tocando nos ouvidos enquanto eles escrevem novos requisitos para o próximo projeto.

Se você estiver interessado em documentar seu código e fornecer contexto para o grupo de manutenção, esse requisito será atendido automaticamente. Então não seja uma merda!

No final, seja 21% ou 29%, ninguém vai se importar. O cliente terá seu material revisado por algum desenvolvedor independente e ele entenderá melhor o que você fez.

Eu conheci muitos programadores que não entendem como existem pessoas que atualmente não trabalham neste projeto.

Para eles tudo o que eles sabem, é conhecido por todos.

Se alguém não conhece TUDO que conhece atualmente, então essas pessoas são "idiotas" para eles.

Com esse padrão, você pode forçar as pessoas a entrarem em um local com comentários por escrito.

Eles podem escrever comentários inúteis 99% do tempo, mas às vezes eles podem realmente escrever uma das coisas que "TODOS SABEM", e alguém novo na equipe pode realmente não passar 16 horas procurando por um bug (que someonelse já resolvido, mas foi desfeito por outro motivo) que teria sido óbvio com um comentário naquele ponto do código.

Ter comentários em linhas com erros não óbvios também pode ajudar a evitar que futuros programadores quebrem completamente um programa por acidente (especialmente quando a parte "estar quebrado" não for óbvia ao fazer um teste rápido).