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

desenvolvedor júnior aqui.

Atualmente, estou trabalhando sozinho em um aplicativo da web para um grande cliente da minha empresa. Comecei no mês passado. O cliente deseja pelo menos 25% dos comentários em cada um de seus projetos de software.

Eu verifiquei o código de aplicativos anteriores e aqui estão minhas observações:

• cada arquivo começa com um bloco de comentários (pacote, data da última atualização, nome da minha empresa e direitos autorais)

• todas as variáveis ​​são comentadas com seus nomes // nameOfCustomer public String nameOfCustomer

• todos os getters e setters são comentados

• muito poucos comentários úteis

Parece que os desenvolvedores colocam o máximo de comentários possível para atingir esse limite de 25%, independentemente da qualidade e utilidade. Minha empresa me diz que "fazemos como o cliente deseja".

Não falei diretamente com o cliente sobre isso. Aqui estão os meus argumentos até agora:

• linhas inúteis para ler e escrever (perda de tempo)
• os comentários às vezes não são atualizados (fonte de confusão)
• os desenvolvedores têm menos probabilidade de usar ou confiar em comentários úteis reais

Qual o seu conselho sobre esse assunto? Como devo lidar com a situação?

Todas as outras respostas e comentários aqui realmente me impressionaram, porque são muito contrárias à minha primeira reação e muito contrárias à atitude que testemunhei em meus colegas de trabalho. Então, eu gostaria de descrever uma abordagem alternativa, mesmo que apenas por ser a voz dissidente .

O princípio norteador desta resposta é "Encantar o cliente". Encantar o cliente não significa apenas atender às suas expectativas; significa entender suas solicitações tão profundamente que você pode interpretar o que eles dizem da maneira que querem e entregar acima e além do que eles pedem. Outras respostas parecem ser guiadas pelo princípio da conformidade maliciosa, que considero repugnante; além disso, é uma prática comercial questionável, pois é uma maneira ruim de atrair clientes fiéis.

Para mim, quando ouço o cliente dizer: "Quero 25% de comentários", é o começo de um diálogo. Para mim, está claro que a implicação aqui é "Quero muito texto descritivo, para que os recém-chegados a essa base de código possam começar a funcionar rapidamente", e não "Quero que você adicione aleatoriedade em uma determinada categoria sintática", como outras respostas parece estar pegando. Eu levaria esse pedido a sério e pretendia escrever muitos comentários úteis e descritivos, orientando um recém-chegado à estrutura do código, apontando decisões de engenharia surpreendentes e descrevendo o raciocínio que lhes era introduzido e fornecendo um inglês de alto nível descrições de seções de código complicadas (mesmo que não tenham nenhuma surpresa). Essa intenção e compreensão é o ponto de partidada discussão - isto é, antes mesmo de começarmos a conversar. Para mim, a implicação da solicitação é tão clara que nem precisa desse esclarecimento; mas se para você não está claro, é claro que você deve entrar em contato com eles!

Ok, então para onde vai a caixa de diálogo se esse é o ponto de partida? A próxima parte da caixa de diálogo é assim:

1. Eu esperaria que este 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 querem trabalhar. Pode demorar vários minutos de discussão para discutir esse processo e por que é um trabalho adicional, mas vou omitir aqui porque, como programador profissional, espero que você saiba o quão difícil é fazer bons 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 talvez seja necessário reduzir o orçamento do recurso; oupodemos precisar comprometer a qualidade e a quantidade dos comentários. Esta parte vai ser um pouco de negociação. Mas, na minha opinião, você deve ser muito franco quanto aos custos de realizar esse trabalho extra e garantir que seja um recurso tão importante para o cliente que ele esteja disposto a assumir esses custos. E se eles são - ótimos! Você ganha tempo e dinheiro extras, e eles recebem comentários de alta qualidade. Todo mundo ganha. E se o recurso de comentários não for tão importante para eles, eles estão dispostos a perder a capacidade de exibir widgets ou a deixar o prazo chegar ao final do Granuary, 20x6, e todos ganham novamente: obtêm o produto que desejam deseja, 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 não deve 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% dos comentários e informe-os de que você deseja cumprir essa promessa, gerando aleatoriamente 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, gere aleatoriamente aleatoriamente sem dizer a eles que é isso que você fará. Quando eles percebem (e não se), vocês dois perdem muito tempo: estão descontentes com o produto que adquiriram e você recebe um boca-a-boca negativo.
5. Não tente convencê-los de que não querem comentários. Eles claramente querem comentários. Discuta as compensações de várias abordagens: sim! Discuta maneiras alternativas de tornar o iniciante da base de código amigável: sim! Diga a eles que eles não sabem o que querem: eh, não. Você quer trabalhar com eles para conseguir o que eles querem; entenda o que é isso e descubra a melhor forma de entregar isso a eles em um orçamento que eles aprovam, priorizando os recursos de que mais se preocupam se os recursos que eles têm são insuficientes.
6. Não dê desculpas sobre a dificuldade de escrever comentários. Escrever código é difícil; 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 em que elas se preocupam, a saber, como o esforço extra necessário as afeta.

O cliente é rei. Portanto, como contratado, você deve encontrar o que o cliente definiu como padrão de qualidade. Ou você corre o risco de estar fora.

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

• Padrões de qualidade contratuais: o código entregue deve estar em conformidade ou, caso contrário, é uma quebra de contrato. Sem escolha

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

• Critérios ad-hoc definidos por duas pessoas no cliente. Aqui você pode participar da discussão. Há esperança :-)

Neste último caso, pode haver alguma flexibilidade e você pode tentar diplomaticamente defender o argumento. Aqui estão 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 deverão ser feitas nos comentários ou os comentários poderão 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.
• Quantidade não é qualidade
• Esta divertida coleção de comentários inúteis no StackOverflow .
• Este artigo argumenta que uma alta taxa de comentários pode até ser o sinal de um cheiro de código.

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

• Código limpo (sugira o livro ao seu cliente: há uma seção convincente dedicada a comentários e código de auto-documentação).
• Prática de documentação: as coisas mais difíceis de entender e, portanto, as informações mais valiosas, como por exemplo, a relação e a interação entre as 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 estiver convencido, você poderá propor uma alternativa experimental, usando ferramentas para gerar automaticamente documentação com comentários, como javadocou doxygen. Propor com isso mudar o foco da quantidade (25% do código) para a qualidade (gerar um javadoc compreensível).

O cliente deseja pelo menos 25% dos comentários em cada um de seus projetos de software.

O cliente realmente deseja 25% dos comentários ou deseja 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, ele vê apenas a parte superior do iceberg.

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

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

Converse com seu cliente / supervisor / o que quer que seja 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 (eu recomendo o livro também) e, assim, o código autoexplicativo resultante.

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

Isso me lembra aquelas respostas idiotas 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, é possível 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 adequadamente formadas e adicionaram ruído artificial quando o sistema solicitou que adicionassem mais substância real

Às vezes, uma pergunta 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 a dizer. Se nada mais, deve ser totalmente óbvio que a maneira de contornar uma restrição de personagem não é apenas despejar ruído aleatório em seu post.

Essa situação de comentários que você está enfrentando é quase a mesma. Seus desenvolvedores aceitaram uma solicitação de comentários e a implementaram lançando ruído aleatório em seu código. 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 da substância. Use mais palavras, melhores palavras, as melhores palavras para documentar o efeito das funções. Expanda suas explicações. Descreva casos de borda com mais detalhes.

No entanto, voltando ao ponto original, o cliente também é parcialmente culpado, 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.

Não sei qual é o grande problema com esse requisito.

Apenas pela doxygenation básica do seu código, você provavelmente já está com 10% ou mais. E vamos fazer mais 5% dos comentários que você escreveu (alguns escrevem mais, mas 5% parece uma estimativa conservadora se você não fez um voto de silêncio). Neste ponto, é de cerca de 15% (sim, sim, eu sei, 5% de 90% é inferior a 5%, não escolha). Se o seu doxygen for inferior a 10%, talvez seus métodos sejam muito longos; geralmente é uma boa ideia dividi-los em grupos menores (principalmente privados / protegidos) ou usar classes auxiliares mais 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. Tenha algumas tabelas ou arte ASCII (ou código doxygen que gera coisas mais agradáveis ​​quando renderizadas). Não sei, é claro, do que se trata o seu projeto, mas acredito que você pode fazer isso sem comentários fictícios (além do padrão da doxygenation) e chegar a algo próximo de 25%.

Se for apenas, digamos, 20% e não 25% - eu tenho certeza que o cliente acabou de dar 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 incluir; e mostre a eles um exemplo de arquivo comentado para ver se estão satisfeitos. Se eles são, é isso, se eles acham que algo está faltando, eles dirão o que está faltando. Eles não dirão "Não podemos sugerir nenhum comentário extra possível, 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 no seu código é uma excelente meta, e isso faz o cliente feliz. Agora, escrever 25% de comentários ruins como "i + = 1; // aumentar i em 1" deve estar abaixo de você; portanto, dedique um tempo, escreva comentários úteis e aproveite a sensação de que você realmente é pago para fazer algo que deve fazer de qualquer forma.

Todos sabemos que esse é um requisito porcaria. A questão interessante aqui é

como reagir?

Eu acredito muito em tornar os problemas visíveis. Aqui eu usaria o fato de que o dinheiro fala.

Peça-me para fazer isso e direi com certeza que isso adicionará 1% ao meu lance. Ah, mas isso adicionará 20% a todos os lances futuros de manutenção.

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

Como alternativa, proponho a criação de documentação destinada a obter um programador de manutenção com um conjunto definido de qualificações assumidas, a fim de acelerar as idéias por trás do projeto. Ou, com certeza, eu poderia lhe dar 25% de comentários. Você decide.

Sim, 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 digo para mim mesmo: Então, isso é o 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ê dá a eles o que eles querem. Se eu trabalhasse em uma concessionária de carros e um cliente dissesse que queria uma caminhonete, eu não discutiria com ele sobre se ele realmente precisa de uma caminhonete e o questionaria sobre o que ele espera transportar nela. 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 estão tão distantes que eu tento discutir o assunto com ele, talvez o convença a concordar com algo mais racional. Às vezes isso funciona, às vezes não. No final, se não consigo mudar de idéia, dou o que ele quer. Se ele voltar mais tarde e disser: Ah, isso realmente não atendeu aos meus requisitos de negócios, poderemos cobrar mais dele pelo que dissemos a ele na primeira vez. O quanto você pode negociar com o cliente depende de quanto eles confiam nos seus conhecimentos, como o contrato deles com você se encaixa na organização e, francamente, como eles são tímidos.

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

Lembre-se de que as pessoas com quem sua empresa está negociando podem ou não ser quem inventou essa regra de 25%. Poderia ser uma regra imposta a eles de cima para baixo.

Eu vejo cinco respostas possíveis:

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

Dois. Recuse-se a fazê-lo. Provavelmente, você será demitido ou, se a empresa concordar com você, fará com que você perca o contrato. Isso parece improdutivo.

Três. Escreva comentários inúteis para preencher o espaço, o tipo de comentários que apenas repete o que está no código e que qualquer programador capaz de modificar o código poderá ver em 2 segundos. Já vi muitos comentários como esse. Anos atrás, trabalhei para uma empresa na qual fomos obrigados a 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 esses comentários são um ônus 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 olhará. Se houver alguma dúvida sobre isso, deixe 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 veja os comentários inúteis.

Quatro Se você quiser adicionar comentários inúteis redundantes, talvez valha a pena escrever um programa para gerá-los. Algo como um investimento adiantado, mas poderia economizar um monte de digitação no caminho.

Quando comecei neste negócio, uma empresa na qual trabalhei usava um programa anunciado como "Grava sua documentação para você! Documentação completa para cada programa!" O sistema exigia que atribuíssemos a todas as variáveis ​​nomes essencialmente sem sentido e, em seguida, tivéssemos uma tabela fornecendo um nome significativo para cada variável, então basicamente o que a "documentação automática" substituiu o nome sem sentido que nos forçou a usar com um nome com significado. 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, alguém poderia certamente escrever um programa para gerar documentação igualmente inútil 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, poderia ser um bom exercício.

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

Lembro-me de uma vez que um empregador disse que começaria a medir a produtividade dos programadores por 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 há mais escrita

x=x+4;

Em vez disso, vou escrever:

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

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

Então aqui, se eles vão contar linhas de comentários, reduza cada linha e continue com a ideia na próxima linha. Se houver uma alteração no que está nos comentários, não atualize o comentário existente. Coloque uma data, copie o texto inteiro e escreva "Atualizado" e uma nova data. Se o cliente questionar, 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 geralmente é visto em requisitos idiotas, como uma complexidade ciclomática máxima que leva a códigos mais complexos, 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 deseja e sua empresa concordou em fornecer, a menos que o gerente de controle de qualidade desenvolva uma dose de bom senso, você está preso.

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

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

Depois de desenvolver um relacionamento de confiança com o cliente, eles estarão em melhor posição para ouvir seu raciocínio - você pode achar que essa é uma demanda tola de uma pessoa que já foi influente e que tem muito pouco apoio interno.

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

Estou decepcionado 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 adiante. 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, para enumerar alguns indicadores de qualidade.

Isso não me parece estúpido ou ridículo. As pessoas que escreveram os requisitos provavelmente não são programadores. Eles podem ter tido uma experiência ruim com um projeto anterior. O pessoal de manutenção está reclamando: "Nada disso está documentado!". Ele está tocando nos ouvidos enquanto eles escrevem novos requisitos para o próximo projeto.

Se você quer documentar seu código e fornecer contexto para o grupo de manutenção, esse requisito será cumprido automaticamente. Portanto, não se preocupe com isso!

No final, seja 21% ou 29%, ninguém se importará. O cliente analisará suas coisas 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 sabem, é conhecido por todos.

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

Com esse padrão, você pode forçar as pessoas a habituar-se a escrever comentários.

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

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