Check-in do código “comentado” [fechado]


94

Ok, aqui está algo que causou algum atrito no meu trabalho atual e eu realmente não esperava. O desenvolvimento de software interno organizado é um novo conceito aqui e eu fiz um primeiro rascunho de algumas diretrizes de codificação.

Propus que o código "comentado" nunca deve ser verificado no repositório. Afirmei isso porque o repositório mantém um histórico completo dos arquivos. Se você estiver removendo o código funcional, remova-o completamente. O repositório mantém suas alterações para que seja fácil ver o que foi alterado.

Isso causou certo atrito, pois outro desenvolvedor acredita que seguir esse caminho é muito restritivo. Este desenvolvedor gostaria de poder comentar algum código no qual está trabalhando, mas está incompleto. Este código, então, nunca teria sido verificado antes e não seria salvo em nenhum lugar. Vamos usar o TFS, então sugeri que arquivar as alterações seria a solução mais correta. No entanto, ele não foi aceito porque ele gostaria de poder fazer o check-in de alterações parciais que podem ou não ser implantadas.

Queremos eventualmente chegar a um ponto em que estejamos aproveitando ao máximo a integração contínua e implantando automaticamente em um servidor web de desenvolvimento. Atualmente não existe uma versão de desenvolvimento de servidores web ou servidores de banco de dados, mas tudo será alterado em breve.

Enfim, quais são seus pensamentos? Você acredita que o código "comentado" é útil ter no repositório?

Estou muito interessado em ouvir outras pessoas sobre este assunto.

Edit: Para fins de clareza, não usamos ramos privados. Se o fizéssemos, eu diria para fazer o que quiser com seu branch privado, mas nunca mesclar código comentado com o tronco ou qualquer branch compartilhado.

Editar: Não há nenhuma razão válida para não usarmos ramos privados ou por usuário. Não é um conceito do qual eu discordo. Nós apenas não configuramos dessa forma ainda. Talvez esse seja o meio-termo eventual. Por enquanto, usamos prateleiras TFS.


2
Certifique-se de treinar totalmente seus desenvolvedores sobre o uso adequado do TFS. Meu grupo de trabalho teve problemas significativos com o TFS, o que resultou na perda de código para mim. Pode ter sido um erro "ID10T", mas ainda não confio no TFS.
James Schek,

@John: Algum motivo pelo qual você não permite agências privadas? Isso resolveria o problema, ele poderia facilmente enviar e salvar qualquer coisa lá, e você não seria incomodado no branch principal.
Frank,

@null - conforme mencionado na edição, não tenho nenhum problema com eles, apenas não fizemos isso ainda. O problema, porém, neste cenário é que não lançaremos de uma filial privada e ele quer uma solução parcial implantada.
John,


Respostas:


123

Pode haver outras pessoas com experiências diferentes, mas, no meu caso, verificar o código incompleto é uma ideia horrível, ponto final.

Aqui estão os princípios que aprendi e tento seguir:

  • Faça check-in com frequência - pelo menos uma vez, mas de preferência muitas vezes por dia
  • Verifique apenas a funcionalidade completa
  • Se o primeiro e o segundo conflito (por exemplo, leva mais de um dia para fazer a funcionalidade funcionar), a tarefa é muito grande - divida-a em tarefas menores que podem ser concluídas.

Isso significa:

  • O código comentado nunca deve ser verificado, pois não é funcional
  • Comentar não é uma estratégia de arquivamento válida, portanto, seja um código que ainda não foi concluído ou que está sendo retirado, comentar e verificar não faz nenhum sentido.

Então, em resumo, NÃO! Se o código não estiver pronto para ir para o próximo estágio (o que for para você: IntTest / QA / UAT / PreProd / Prod), ele não deve ser confirmado para um tronco ou branch de multi-desenvolvedor. Período.

Edit: Depois de ler as outras respostas e comentários, acrescentarei que não acho que seja necessariamente uma boa ideia banir o código comentado (não tenho certeza de como você aplicaria isso de qualquer maneira). O que direi é que você deve fazer com que todos em sua equipe aceitem a filosofia que descrevi acima. A equipe em que trabalho o abraça de todo o coração. Como resultado, o controle de origem é um membro da equipe sem fricção, que nos ajuda a fazer nosso trabalho.

Pessoas que não adotam essa filosofia geralmente causam janelas quebradas e muitas vezes ficam frustradas com o controle de origem. Eles vêem isso como um mal necessário, na melhor das hipóteses, e algo a evitar, na pior; o que leva a check-ins pouco frequentes, o que significa que os changesets são enormes e difíceis de mesclar, o que aumenta a frustração, torna os check-ins algo a serem evitados ainda mais, etc. Em última análise, isso é uma coisa de atitude, não realmente uma coisa de processo. É fácil colocar barreiras mentais contra ele; é fácil encontrar motivos pelos quais não funcionará, assim como é fácil encontrar motivos para não fazer dieta se você realmente não quiser. Mas quando as pessoas não querem fazê-lo e estão empenhados em mudar seus hábitos, os resultados são dramáticos. O ônus de vendê-lo com eficácia está sobre você.


2
Eu concordo com o seu esclarecimento - nunca faça o check-in pela metade do código no "porta-malas" ou qualquer equivalente. Sempre deve haver uma ramificação / tronco que seja a versão "este código está sempre funcionando". Vá em frente e faça o check-in pela metade em uma filial de desenvolvimento privada, espelho local, prateleira, qualquer coisa.
James Schek,

2
Os comentários do @Eddie, por definição, não são obrigados a ficar em sincronia com o resto da base de código. Eles podem se tornar obsoletos e enganosos e contribuir para a quebra de janelas do sistema. Todas essas coisas são riscos para o tempo do desenvolvedor. Já temos o suficiente deles. É fácil evitar este
Rex M,

2
@Rex M: IMO, os comentários são uma parte essencial do código. Em qualquer código que mantenho, os comentários têm a garantia de ficar em sincronia com o resto da base de código. O código em que os comentários estão fora de sincronia está corrompido. Você só pode não saber ainda.
Eddie

2
@John: Parece que esse defeito foi causado por um descuido do desenvolvedor. Como a proibição de fazer check-in do código comentado teria impedido o desenvolvedor de fazer esse descuido? A proibição apenas dá a você DUAS coisas para punir em vez de uma. Não impede o descuido.
Eddie

9
Eu quase votei nisso, mas é realmente raro eu conseguir algo em que estou trabalhando no estado de check-in em apenas um dia de trabalho. Suponho que seja possível que você seja um desenvolvedor muito melhor do que eu, mas prefiro acreditar que trabalho em coisas mais difíceis do que você. :-)
TED de

43

"Nunca" raramente é uma boa palavra para usar em diretrizes.

Seu colega tem um ótimo exemplo de quando pode ser apropriado fazer o check-in do código comentado: quando está incompleto e pode quebrar o aplicativo se o check-in estiver ativo.

Para a maior parte, comentar o código morto é desnecessário em um sistema bem gerenciado e controlado por mudanças. Mas nem todo código comentado está "morto".


9
Discordo. Se o código estiver incompleto, por que ele está sendo verificado em primeiro lugar? Os sistemas de controle de origem modernos têm mecanismos para carregar funcionalidades em andamento sem comprometer-se com o tronco.
Rex M de

9
+1, às vezes essa é a coisa mais apropriada a fazer. Nem sempre, mas também nunca . Nunca é fácil dizer, mas é muito restritivo.
Eddie

@Rex Não acho que haja informações suficientes na postagem original para determinar a diferença entre enviar uma funcionalidade em andamento e enviar para o tronco.
Jason Coco,

Rex - o que é? Nunca faça check-in incompleto? Ou nunca faz o check-in incompleto no porta-malas? Essas não são a mesma coisa.
James Schek,

@Jason "o desenvolvedor gostaria de poder comentar algum código em que está trabalhando, mas está incompleto". Parece que ele quer verificar a funcionalidade em andamento para mim.
Rex M de

24

O código comentado nunca deve ser verificado com o propósito de manter o histórico. Esse é o ponto de controle de origem.

As pessoas estão falando muito de ideais aqui. Talvez ao contrário de todo mundo, eu tenha que trabalhar em vários projetos com várias interrupções com o "mundo real" ocasionalmente interrompido meu dia de trabalho.

Às vezes, a realidade é que preciso fazer o check-in do código parcialmente completo. É o risco de perder o código ou o código incompleto do check-in. Nem sempre posso me dar ao luxo de "terminar" uma tarefa, por menor que seja. Mas eu não desligar meu laptop a partir da rede sem verificar-in todo o código.

Se necessário, criarei meu próprio branch de trabalho para confirmar alterações parciais.


4
@James, sua última parte é a chave - se você não puder verificar o código de funcionamento, encontre outro lugar para colocá-lo. Seja um galho ou um conjunto de prateleiras ou o que for.
Rex M

Se eu pudesse votar a favor deste mais de uma vez, eu o faria. Meus sentimentos precisamente!
Ola Eldøy de

23

Um caso em que deixo o código comentado:

// This approach doesn't work
// Blah, blah, blah

quando essa é a abordagem óbvia para o problema, mas contém algumas falhas sutis. Claro, o repositório teria, mas o repositório não alertaria ninguém no futuro para não seguir por esse caminho.


6
Se fosse limitado a uma linha, isso poderia ser uma exceção. Prefiro ver um comentário em bloco conciso (algumas linhas no topo) que mencione as razões para escolher uma abordagem em vez de outra. Nesse caso, eu não consideraria isso como "comentado", mas documentado.
John,

3
+1. Um exemplo que vi é onde algo foi quebrado porque o código definiu um soTIMEOUT. A solução era removê-lo. Se você apenas remover a linha de código, alguém pode reintroduzi-la mais tarde, pensando que está corrigindo um bug ao fazer isso, mas na verdade está reintroduzindo um bug.
Eddie

1
Sim, essa ideia é minha - garantir que o bug não seja reintroduzido no futuro. Ao deixar o código real, eles podem ver que não era apenas um bug em como o original foi escrito.
Loren Pechtel,

Para este caso, não considero este um "código comentado", é uma documentação.
hlovdal

1
este é o único exemplo em que deixo código comentado ativo. neste caso, não é a ideia malfeita de alguém flutuando e confundindo os programadores de manutenção, é [esperançosamente] um exemplo legítimo e funcional de código que quebrará completamente o aplicativo, mas de outra forma é a abordagem óbvia.
worc

19

Eu certamente desencorajaria, fortemente, verificar o código comentado. Eu não iria, no entanto, bani-lo de forma absoluta. Às vezes (se raramente) é apropriado verificar o código comentado no controle de origem. Dizer "nunca faça isso" é muito restritivo.

Acho que todos concordamos com estes pontos:

  • Nunca verifique o código morto no controle de origem
  • Nunca verifique o código quebrado (não funcionando) no controle de origem, pelo menos nunca no tronco e apenas muito raramente em uma filial privada, YMMV
  • Se você comentou temporariamente algo ou quebrou algo para fins de depuração, não faça o check-in do código até restaurá-lo à forma correta

Alguns estão dizendo que há outras categorias, como código removido temporariamente ou uma melhoria incremental, mas incompleta, que inclui uma pequena quantidade de código comentado como documentação do que vem a seguir, ou um trecho muito curto (idealmente de 1 linha) de comentado nosso código mostrando algo que deveria nunca ser adicionado novamente. Código comentado SEMPRE deve ser acompanhado por um comentário que diga por que ele foi comentado (e não apenas excluído) e fornece a vida útil esperada do código comentado. Por exemplo, "O código a seguir faz mais mal do que bem, por isso está comentado, mas precisa ser substituído antes do lançamento XXX."

Um comentário como o acima é apropriado se você estiver entregando um hotfix para interromper o sangramento de um cliente e não tiver a oportunidade imediata de encontrar a solução definitiva. Depois de entregar o hotfix, o código comentado é um lembrete de que você ainda tem algo que precisa ser consertado.

Quando faço check-in do código comentado? Um exemplo é quando estou removendo provisoriamente algo que acho que há uma grande probabilidade de ter que ser adicionado novamente em um futuro próximo, de alguma forma. O código comentado existe para servir como um lembrete direto de que está incompleto. Claro, a versão antiga está no controle de origem e você pode apenas usar um comentário FIXME como um sinalizador de que algo mais é necessário. No entanto, às vezes (se não frequentemente) o código é o melhor comentário.

Além disso, quando um bug é corrigido removendo uma linha (ou mais raramente, duas linhas) de código, às vezes apenas comento a linha com um comentário para nunca reativar o código com um motivo. Esse tipo de comentário é claro, direto e conciso.

Rex M disse: 1) Verifique apenas a funcionalidade completa, 2) [Se] a tarefa for muito grande - divida-a em tarefas menores que podem ser concluídas.

Em resposta: Sim, este é o ideal. Às vezes, nenhuma das opções é alcançável quando você está trabalhando no código de produção e tem um problema crítico imediato para corrigir. Às vezes, para concluir uma tarefa, você precisa colocar uma versão do código no campo por um tempo. Isso é especialmente verdadeiro para alterações no código de coleta de dados, quando você está tentando encontrar a causa raiz de um problema.

Para a instância específica que está sendo questionada na questão mais geral ... contanto que o desenvolvedor esteja verificando o código comentado em um branch privado que ninguém verá, exceto aquele desenvolvedor (e talvez alguém com quem o desenvolvedor esteja colaborando), faz pouco mal. Mas esse desenvolvedor deve (quase) nunca entregar tal código no tronco ou equivalente. O tronco deve sempre ser construído e sempre funcionar. Entregar código inacabado ao tronco é quase sempre uma ideia muito ruim. Se você permitir que um desenvolvedor verifique o código inacabado ou temporário em um branch privado, você terá que contar com o desenvolvedor para não esquecer de limpar o código antes de entregá-lo no tronco.

Para esclarecer em resposta a comentários a outras respostas, se o código for comentado e verificado, minha expectativa de que o código funcionará se não for comentado diminui com o tempo que o código foi comentado. Obviamente, as ferramentas de refatoração nem sempre incluirão comentários em sua refatoração. Quase sempre, se coloco o código comentado na produção, o código está lá para servir como um comentário refinado, algo mais específico do que a prosa, de que algo precisa ser feito lá. Não é algo que deveria ter uma vida longa.

Finalmente, se você puder encontrar código comentado em cada arquivo de origem, então algo está errado. Entregar código comentado no tronco por qualquer motivo deve ser um evento raro. Se isso ocorrer com frequência, torna-se desordenado e perde seu valor.


4
@camh: Um sistema de rastreamento de problemas não fornecerá o mesmo contexto que um lembrete que está no próprio código, no contexto, com um comentário sucinto sobre o problema. O rastreamento de problemas não está profundamente integrado ao IDE. Sua sugestão descarta muitas informações por uma questão de dogma.
Eddie

1
@John: Não, eu trabalho em coisas com milhões de SLOC e dezenas de milhares de arquivos de origem. Se você acha que o tipo de comentário a que me refiro é desordem, isso significa que você não me entende e / ou que não estou sendo claro o suficiente. Estou falando de um caso extremo, não uma ocorrência comum, como já disse muitas vezes em threads em resposta à sua pergunta. E ei, sua loja não é aquela que não tem agências privadas? Não seja arrogante comigo.
Eddie de

1
@John: Para um exemplo, veja meu último comentário em stackoverflow.com/questions/758279/… - e me dê uma maneira melhor de prevenir a RE-introdução desse bug. Ou para @camh, diga-me como um sistema de rastreamento de problemas evitaria a reintrodução desse bug. Quando você trabalha em equipamentos 5-9 de missão crítica, coisas assim são importantes.
Eddie de

1
@John: Como não posso ficar ofendido com "Tenho a nítida impressão de que você trabalha principalmente em coisas de pequena escala"? aka, só porque discordamos em algo muito pequeno, devo ser inexperiente? É claro que você sempre tem direito à sua opinião, e não há problema em discordarmos. Mas observe que, quando discordo de você, não critico seu nível de experiência apenas porque vemos as coisas de maneira diferente. Na verdade, 98% ou 99% concordo com você. Eu simplesmente não gosto de absolutismo.
Eddie

1
@Eddie - A encarnação atual de sua resposta está muito mais perto de estar de acordo com o que eu consideraria a melhor prática. Como sempre, quando se trata de práticas recomendadas, você nunca obterá 100% de concordância de todos de que algo é uma prática recomendada legítima. Eu não esperava quando postei minha pergunta :)
John,

15

Acho que nunca é uma condição muito forte.

Eu costumo comentar, fazer check-in, executar os testes, pensar e remover comentários após o próximo lançamento.


Se você não executou os testes, não deve fazer o check-in ainda. Não faça check-in do código que irá falhar nos testes ou de outra forma interromper a compilação.
John Saunders,

@John Saunders: Isso depende do que o check-in faz em seu sistema de controle de origem. Se você estiver usando algo como ClearCase com UCM, os check-ins estarão sempre em uma ramificação privada e uma etapa separada será necessária para mover para o equivalente a "TRUNK".
Eddie

Exatamente, mas infelizmente um grande número de desenvolvedores por aí pensam que "cometer" significa "introduzir mudanças no tronco", graças ao CVS e ao SVN, eu acho. Felizmente, novos sistemas como o GIT estão ensinando novos métodos ...
pablo

@john, eu quis dizer: comentar, testar, verificar ..! Você está certo.
Fortyrunner de

14

Em geral, fazer check-in do código comentado é errado, pois cria confusão entre aqueles que não são o autor original e precisam ler ou corrigir o código. Em qualquer caso, o autor original muitas vezes acaba confuso sobre o código depois de 3 meses.

Eu defendo a crença de que o código pertence à empresa, ou equipe, e que é sua responsabilidade facilitar as coisas para seus colegas. Verificar o código comentado sem também adicionar um comentário sobre por que ele está sendo retido é o mesmo que dizer:

Não me importo se você ficar confuso sobre por que essas coisas estão aqui. Minhas necessidades são mais importantes que as suas, por isso fiz isso. Não sinto necessidade de justificar a você, ou a qualquer outra pessoa, por que fiz isso.

Para mim, o código comentado é normalmente visto como um sinal de desrespeito de um colega de trabalho menos pensativo.


3
A última linha da sua postagem está certa. Eu gostaria de poder votar em você mais de uma vez
MikeJ,

2
Às vezes, o que é conveniente para você não é a única consideração. É claro que uma das responsabilidades importantes de um desenvolvedor é facilitar as coisas para os futuros desenvolvedores, mas isso tem que competir com outros interesses. Olhar para algo levemente inconveniente e assumir imediatamente que foi adicionado apenas para irritá-lo mostra uma atitude muito importante de sua parte.
Andrew Shelansky

6

Eu concordo amplamente com o princípio de que o código comentado não deve ser verificado. O sistema de controle de origem é um recurso compartilhado e seu colega está, até certo ponto, usando-o como seu bloco de notas pessoal. Isso não é muito atencioso com os outros usuários, especialmente se você subscrever a ideia de propriedade compartilhada da base de código.

O próximo desenvolvedor a ver aquele código comentado não teria ideia de que é um trabalho em andamento. Ele está livre para mudar isso? É um código morto? Ele não sabe.

Se a alteração do seu colega não estiver em um estado em que possa ser verificada, ele precisa concluí-la e / ou aprender a fazer alterações menores e incrementais.

"Verificando mudanças parciais que podem ou não ser implantadas" - presumivelmente isso também significa que podem ou não ser testadas? Essa é uma ladeira escorregadia para uma base de código muito pegajosa.


6

Quando você precisa adicionar um pequeno recurso ou correção de bug como AGORA, dentro dos próximos 3 minutos e você tem que consertar um arquivo que tem algum código desenvolvido pela metade, eu diria que está tudo bem, necessidades práticas prevalecem sobre ideais pragmáticos no campo de batalha.


Onde o gerenciamento de mudanças se encaixa neste cenário? Concordo que há lojas onde tudo é sempre um grande incêndio, mas isso não significa que as coisas devam ser feitas assim. Eu também sugeriria que essa poderia ser a razão do problema. Controle insuficiente sobre a base de código.
John,

1
Eu concordo totalmente que esse tipo de coisa DEVE ser evitado, mas por algum motivo, a administração parece não concordar :)
Robert Gould

5

Isso mostra uma diferença fundamental em duas escolas de pensamento: aqueles que só verificam o código em funcionamento com o qual estão satisfeitos e sentem que vale a pena salvar, e aqueles que verificam seu trabalho para que o controle de revisão esteja lá para protegê-los contra a perda de dados.

Eu caracterizaria o último como "aqueles que gostam de usar seu sistema de controle de revisão como um backup de fita do pobre", mas isso seria me dar uma dica sobre em que campo estou. :-)

Meu palpite é que você é do campo do "código bom" e ele do campo do "código de trabalho".

[EDITAR]

Pelos comentários, sim, acertei.

Como eu disse, estou com você, mas pelo que posso dizer, essa é uma opinião minoritária, tanto aqui no stackoverflow quanto onde trabalho. Como tal, não acho que você possa realmente consagrar isso em seus padrões de desenvolvimento como a única maneira de operar. Não se você quiser que os padrões sejam seguidos de qualquer maneira. Uma coisa que um bom líder sabe é nunca dar uma ordem que sabe que não será seguida.

btw: Bons editores ajudarão a manter as versões antigas. Por exemplo, no Emacs eu defini as versões antigas e as versões antigas mantidas como 10, o que significa que ele mantém as últimas 10 salvações dos meus arquivos. Você pode considerar isso como uma forma de ajudar em seu argumento contra a multidão de controle de revisão como backup. No entanto, você nunca vai ganhar a discussão.


1
Isso foi afirmado aqui também. Na minha opinião, no entanto, o repositório não é uma ferramenta de prevenção de perda de dados. É um sistema de controle de revisão. Como estamos usando o TFS, ele pode usar o shelving para fazer backup de código incompleto. Ele também pode usar uma ferramenta de backup ou colocar o código em um compartilhamento de backup.
João,

1
Os backups IDE não protegem contra perda de dados. Os sistemas de backup corporativo nem sempre atendem às necessidades de perda de dados de código. O controle de origem é um sistema que pode lidar facilmente com ambas as necessidades. É relativamente fácil desenvolver uma política que atenda às necessidades de ambos os campos, em vez de excluir um ou outro.
James Schek,

De que forma meus backups do Emacs não me protegem, James? BTW: Concordo inteiramente com sua última frase.
TED de

Os backups do Emacs são feitos para reverter a um estado anterior em um arquivo específico. Direcionar arquivos de backup para um servidor de arquivos não é habilitado por padrão e exige que eu implore ao administrador do sistema por espaço em um servidor de arquivos. Se eu tivesse um FS, eu apenas colocaria todo o projeto no FS e pronto. Além disso, o "estado" completo de um espaço de trabalho / projeto são "dados" importantes para mim. O Emacs (e a maioria dos IDE) não tem mecanismo para salvar isso.
James Schek,

@ ted.dennison: Olhando para as pontuações das duas principais respostas, eu diria que sua opinião é a opinião da maioria sobre o SO.
Eddie

4

Na minha experiência, as opções do desenvolvedor são código comentado

Às vezes, novos back-ends são construídos em paralelo, com as chaves de ativação comentadas no controle de origem.

Algum recurso bizarro de que precisamos uma vez na lua azul, mas nenhum cliente vai precisar, é frequentemente implementado dessa forma. Essas coisas geralmente apresentam um alto risco de ignorar a segurança ou a integridade dos dados, então não as queremos ativas fora do desenvolvimento. Exigir que um desenvolvedor o usasse para descomentar o código primeiro parece ser a maneira mais fácil de obtê-lo.


4

Outro motivo para o check-in do código comentado:

Você está modificando o código existente e encontrou um bug sutil, fácil de ignorar e talvez até pareça correto à primeira vista. Comente, coloque a correção em seu lugar e adicione comentários sobre o que está acontecendo e por que foi modificado. Verifique isso para que seus comentários sobre a correção estejam no repositório.


5
+1: Deixar o código comentado no lugar - se e somente se for conciso e não obstrutivo - evita que alguém esqueça "não faça isso" e reintroduza o bug. ESPECIALMENTE quando a correção envolve a remoção de linhas de código, não a reescrita de linhas de código.
Eddie

Definitivamente na remoção de linhas de código. Este é um bom ponto.
quinta

1
Discordo. É necessário deixar um comentário sobre o que evitar, mas não em forma de código, em vez de descrevê-lo em palavras.
thSoft

3

Talvez a verdadeira questão aqui seja se os desenvolvedores devem ter permissão para verificar o código incompleto?

Esta prática parece ser contraditória ao seu objetivo declarado de implementar integração contínua.


3

Depende. Se estiver sendo deixado lá para fins de ilustração, talvez. Pode ser útil durante a refatoração. Caso contrário, e geralmente, não. Além disso, comentar código inacabado está sujeito a falhas e desperdício de tempo. Melhor ele quebrar o código em partes menores e fazer o check-in quando funcionarem.


3

Minha visão: se os desenvolvedores estão trabalhando em seus próprios branches, ou em sua própria área de sandbox, eles devem ser capazes de fazer o check-in o que quiserem. É quando eles verificam o código em um branch compartilhado (um branch de recurso, ou um branch de equipe ou, claro, MAIN / trunk) que o código deve ser o mais puro possível (sem código comentado, sem mais FIXMEs, etc).


3
Não existe um único projeto significativo no mundo sem TODOs e FIXMEs ou HACKs no tronco principal. Sonhar.
Robert Gould,

1
@Robert só porque acontece muito não significa que não devamos tentar evitá-lo.
Rex M

2
Uau, isso realmente é um sonho. Código de produção sem FIXMEs? Deve ser absolutamente completo, sem bugs e sem comportamento inexplicável. Oh, espere, um código assim não existe! :)
Eddie

1
Sim, claramente um sonho - eu estava apenas tentando dizer que a barreira para se comprometer em um branch compartilhado é muito maior do que se comprometer em seu branch sandbox / trabalho em andamento pessoal.
Jean,

@jean: Sim, concordamos totalmente com isso.
Eddie

2

Acho que "Nunca" é uma regra muito forte. Eu votaria para deixar alguma margem de manobra pessoal em torno de se as pessoas verificam o código comentado no repositório. O objetivo final deve ser a produtividade do programador, não "um repositório puro".

Para equilibrar essa frouxidão, certifique-se de que todos saibam que o código comentado tem uma data de validade. Qualquer pessoa pode excluir o código comentado se ele já existir por uma semana inteira e nunca estiver ativo. (Substitua "uma semana" pelo que achar melhor para você.) Dessa forma, você se reserva o direito de eliminar a desordem quando a vir, sem interferir muito diretamente no estilo pessoal das pessoas.


2

Eu concordo totalmente que o código comentado não deve ser verificado no repositório, é para isso que serve o controle do código-fonte.

Em minha experiência, quando um programador verifica o código comentado, é porque ele não tem certeza de qual é a solução certa e fica mais feliz em deixar a solução alternativa no código-fonte na esperança de que outra pessoa tome essa decisão.

Acho que isso complica o código e torna difícil de ler.

Não tenho nenhum problema em verificar o código pela metade (para que você obtenha o benefício do controle de origem) que não é chamado pelo sistema ativo. Meu problema é encontrar seções de código comentado sem nenhuma explicação. O dilema resultou na exclusão do código.


2

Acho que o check-in do código comentado em um sistema de controle de código-fonte deve ser feito com extrema cautela, especialmente se as tags de linguagem usadas para comentar o código forem escritas por blocos, ou seja:

/* My commented code start here
My commented code line 1
My commented code line 2
*/

Em vez de uma linha individual, como:

// My commented code start here
// My commented code line 1
// My commented code line 2

(Você entendeu a ideia)

O motivo pelo qual eu usaria muito cuidado é que, dependendo da tecnologia, você deve ter muito cuidado com a ferramenta diff / merge que está usando. Com certo sistema de controle de código-fonte e certa linguagem, a ferramenta diff / merge pode ser facilmente confundida. O diff / merge padrão do ClearCase, por exemplo, é notoriamente ruim para mesclar arquivos .xml.

Se acontecer de as linhas dos blocos de comentários não se fundirem corretamente, pronto, seu código se tornará ativo no sistema quando não deveria. Se o código estiver incompleto e quebrar a compilação, isso é provavelmente o menos maléfico, pois você o verá imediatamente.

Mas se o código passar na construção, ele pode se tornar ativo quando não deveria estar lá e, da perspectiva do CM, isso pode ser um cenário de pesadelo. O controle de qualidade geralmente testa o que deveria estar lá, eles não testam o código que não deveria estar lá, então seu código pode acabar em produção antes que você perceba, e quando for realizado, o código estará lá quando for não deveria, o custo de manutenção se multiplicou muitas vezes (já que o "bug" será descoberto na produção ou pelo cliente, pior lugar ou hora de todos os tempos).


Sim eu concordo. Também não permitimos especificamente o estilo / * * / de comentários em todos os nossos programas C #.
João,

2

A ideia de permitir que o histórico de controle da fonte ilustre a "maneira antiga" de fazer algo em vez de comentá-la e verificar o comentário junto com uma explicação é uma boa ideia em teoria.

No mundo real, no entanto, ninguém nunca olha o histórico de controle de origem nos arquivos em que está trabalhando, a menos que seja parte de um processo de revisão oficial de algum tipo (feito apenas periodicamente) ou se algo não funcionar, e o desenvolvedor não consigo descobrir o porquê.

Mesmo assim, olhar para trás mais do que cerca de 3 versões basicamente nunca acontece.

Em parte, isso ocorre porque os sistemas de controle de origem não facilitam esse tipo de revisão casual. Normalmente você tem que verificar uma versão antiga ou diff contra uma versão antiga, você apenas vê duas versões, e não há uma boa visão concisa do que mudou que pode lhe dar uma ideia rápida do que mudou.

Em parte, é a combinação da natureza humana e das necessidades da equipe. Se eu tenho que consertar algo, e posso consertar em algumas horas, não é provável que eu gaste uma hora investigando versões antigas do código que não estão "ativas" em um mês (que, com cada desenvolvedor verificando em muitas vezes significa voltar muitas revisões), a menos que eu saiba que há algo lá (como se eu me lembrasse de uma discussão sobre mudar algo relacionado ao que estou fazendo agora).

Se o código for excluído e devolvido, então, para todos os intentos e propósitos (exceto para o propósito limitado de uma reversão completa), ele deixará de existir. Sim, ele está lá para fins de backup, mas sem uma pessoa no papel de bibliotecário de código, ele vai se perder.

Minha árvore de controle de origem em meu projeto atual tem cerca de 10 semanas, em uma equipe de apenas cerca de 4 engenheiros, e há cerca de 200 listas de alterações confirmadas. Sei que minha equipe não faz um trabalho tão bom quanto deveria de check-in assim que há algo sólido e pronto para começar. Isso torna bastante difícil confiar na leitura do histórico do código para cada parte do código para capturar todas as alterações importantes.

No momento, estou trabalhando em um projeto em modo de desenvolvimento inicial, que é muito diferente de um projeto em modo de manutenção. Muitas das mesmas ferramentas são usadas em ambos os ambientes, mas as necessidades diferem um pouco. Por exemplo, muitas vezes há uma tarefa que exige que dois ou mais engenheiros trabalhem juntos para construir algo (digamos, um cliente e um servidor de algum tipo).

Se estou escrevendo o servidor, posso escrever o código para a interface de rascunho que o cliente usará e verificá-la como completamente não funcional, para que o engenheiro que está escrevendo o cliente possa atualizar. Isso ocorre porque temos a política que diz que a única maneira de enviar código de um engenheiro para outro é por meio do sistema de controle de origem.

Se a tarefa vai demorar muito, talvez valha a pena criar um branch para nós dois trabalharmos (embora isso seja contra a política em minha organização - engenheiros e líderes de equipe individuais não têm as permissões necessárias em servidor de controle de origem). Em última análise, é uma troca, e é por isso que tentamos não instituir muitas políticas do tipo "sempre" ou "nunca".

Eu provavelmente responderia a essa política de nenhum código comentado dizendo que ela era um pouco ingênua. Bem intencionado, talvez, mas no final das contas improvável de atingir seu propósito.

Embora ver este post vá fazer você voltar ao código que verifiquei na semana passada e remover a parte comentada que nunca foi final (embora funcionou) e também provavelmente nunca será desejada novamente.


Por que tão poucas pessoas concordam com esses argumentos?
pabrams

2

Acho que o código comentado é considerado "desperdício".

Presumo que você esteja trabalhando em um ambiente de equipe. Se você estiver trabalhando por conta própria e comentar o código com um 'todo' e voltar a ele, então é diferente. Mas em um ambiente de equipe, você pode assumir com segurança que, uma vez que o código comentado seja verificado, ele estará lá para ficar e provavelmente causará mais dor do que satisfação.

Se você estiver fazendo revisões de código de pares, isso pode responder à sua pergunta. Se outro desenvolvedor revisar seu código e disser "por que esse código comentado está tentando fazer 'blá'", então seu código falhou na revisão de código e você não deveria verificá-lo de qualquer maneira.

O código comentado apenas levantará questões com outros desenvolvedores - portanto, desperdiçando tempo e energia.

Você precisa fazer a pergunta " por que " o código está comentado. Algumas sugestões:

Se você está comentando o código porque está "inseguro quanto às regras de negócios", então provavelmente você tem um problema com "aumento de escopo" - melhor não sujar sua base de código com requisitos que "seria bom ter, mas não temos tempo para implementar "- mantenha-o limpo com código claro e testes em torno do que realmente está lá.

Se você está comentando o código porque "não tem certeza se é a melhor maneira de fazê-lo", faça uma revisão do código por pares! Os tempos estão mudando, você vai olhar para o código que escreve hoje em 2 anos e achar que é horrível! Mas você não pode sair por aí comentando coisas que você "sabe" que podem ser feitas melhor, mas simplesmente não consegue encontrar uma maneira agora. Deixe quem mantém a base de código a longo prazo determinar se existe uma maneira melhor - basta escrever, testar e trabalhar o código e seguir em frente.

Se você está comentando o código porque "algo não funciona", então FIX IT ! Um cenário comum é "testes interrompidos" ou "tarefas" . Se você os tiver, economizará muito tempo consertando-os ou simplesmente se livrando deles. Se eles podem ser "quebrados" por um período de tempo, provavelmente podem ser quebrados para sempre.

Todos esses cenários potenciais (e aqueles que não mencionei aqui) são perda de tempo e esforço. O código comentado pode parecer um pequeno problema, mas pode ser um indicador de um problema maior em sua equipe.


1

Repositórios são backup de código. Se estou trabalhando no código, mas ele não está concluído, por que não comentar e fazer o check-in no final do dia. Assim, se meu disco rígido morrer durante a noite, não perderei nenhum trabalho. Posso verificar o código pela manhã, descomentar e continuar.

A única razão pela qual eu comentaria isso é porque eu não gostaria de quebrar a compilação noturna.


Um repositório é um sistema de controle de versão, não uma ferramenta de backup em minha mente.
João,

@John: Muitos desenvolvedores verão as duas coisas.
Eddie

@Eddie, eles vão, mas não é. Para backups, há todos os tipos de boas opções, o controle de versão não é realmente uma delas, não é?
David diz para restabelecer Monica em

@ricebowl: Não estou dizendo que concordo com esses desenvolvedores! Muitos lugares não pagam para fazer backup de caixas de desenvolvedores individuais. O check-in de um trabalho incompleto para uma agência privada antes de sair de férias longas funciona como um backup decente do trabalho realizado até agora. Os desenvolvedores são pragmáticos.
Eddie

1

Há claramente uma tensão entre 1) fazer check-in antecipado e 2) sempre manter o repositório em um estado de funcionamento. Se você tiver mais do que alguns desenvolvedores, o último terá cada vez mais precedência, porque você não pode ter um desenvolvedor cagando sobre todo mundo em seu próprio fluxo de trabalho pessoal. Dito isto , você não deve subestimar o valor da primeira diretriz. Os desenvolvedores usam todos os tipos diferentes de barreiras mentais, e fluxos de trabalho individualizados são uma forma de os grandes desenvolvedores espremerem esses Xs extras. Como gerente, seu trabalho não é tentar entender todas essas nuances - nas quais você falhará, a menos que seja um gênio e todos os seus desenvolvedores sejam idiotas -, mas sim permitir que seus desenvolvedores sejam o melhor que podem por meio de suas próprias tomadas de decisão.

Você menciona no comentário que não usa agências privadas. Minha pergunta para você é por que não? Ok, não sei nada sobre o TFS, então talvez haja bons motivos. Porém, depois de usar o git por um ano, devo dizer que um bom DVCS dispersa totalmente essa tensão. Há casos em que acho útil comentar o código enquanto estou construindo um substituto, mas perderei o sono com isso se estiver aplicando isso a outras pessoas. Ser capaz de ramificar localmente significa que posso manter commits significativos para meu processo individual sem ter que me preocupar (ou mesmo notificar) desenvolvedores downstream sobre problemas temporários.


A razão de não usarmos ramos privados é porque apenas recentemente começamos a usar o controle de origem. Sou muito novo na empresa e é minha responsabilidade ajudar a esclarecer tudo isso. Não discordo do conceito, mas agora usamos prateleiras no TFS.
John,

1

Apenas ecoando o refrão. Desencoraje isso a todo custo. Isso torna o código mais difícil de ler e deixa as pessoas se perguntando o que há de bom / ruim naquele código que nem mesmo faz parte do aplicativo no momento. Você sempre pode encontrar mudanças comparando revisões. Se houve alguma cirurgia importante e o código foi comentado em massa, o desenvolvedor deve ter anotado nas notas de revisão sobre check-in / mesclagem.

o código incompleto / experimental deve estar em um branch a ser desenvolvido até a conclusão. a cabeça / tronco deve ser a linha principal que sempre compila e é o que está sendo enviado. assim que o branch experimental for concluído / aceito, ele deve ser mesclado no cabeçalho / linha principal. Existe até um padrão IEEE (IEEE 1042) que descreve isso se você precisar de documentação de suporte.


Quase sempre de acordo. Mas o que você faz quando precisa enviar o código experimental porque está tentando identificar a causa raiz do problema de um site? Ao falar de desenvolvimento, concordo com você, mas ao falar de suporte, às vezes você precisa enviar código experimental.
Eddie

@Eddie - Eu concordo com o código experimental que precisa ser enviado de vez em quando. Mas não deve ser comentado quando não for mais necessário em minha opinião.
João,

@Eddie - eu entendo. mas o branch é uma cópia completa da versão head / release no momento em que você cria o branch. se você fizer um mod, ele deve ser edificável / distribuível. se você gostar das mudanças no branch, você os mescla de volta no head end ou o mantém à mão para depurar / criar perfis quando necessário.
MikeJ

@John: Concordo totalmente. Uma vez que o código experimental não seja mais experimental, ele deve ser deixado no local ou totalmente removido, o que for apropriado. @MikeJ: Boa resposta.
Eddie

1

Eu preferiria ver o código possivelmente quebrado e acessível que não está sendo usado, mas com check-in sobre o mesmo código, estando completamente indisponível. Já que todo software de controle de versão permite algum tipo de 'cópia de trabalho' separada do tronco, é realmente uma ideia muito melhor usar esses recursos.

Código novo e não funcional está bem no porta-malas, porque é novo. Provavelmente não quebra nada que já funcione. Se ele quebrar o código de trabalho, então ele deve ir para um branch, para que outros desenvolvedores possam (se necessário) verificar esse branch e ver o que está quebrado.


1

" Tecido cicatricial " é o que chamo de código comentado. Nos dias anteriores ao uso generalizado de sistemas de controle de versão, o Code Monkeys deixava o código comentado no arquivo caso precisassem reverter a funcionalidade.

A única vez em que é aceitável verificar o "tecido cicatricial" é

  1. Se você tem uma agência privada e
  2. Você não tem tempo para fazer o código compilar sem erros e
  3. Você está saindo de férias longas e
  4. Você não confia em seu VCS, como se você usasse o Visual Source Safe OU .
    [EDITAR]
  5. Você tem um bug sutil que pode ser reintroduzido se o código incorreto não for deixado como um lembrete. (bom ponto de outras respostas).

Quase não há desculpa para o nº 4, porque há uma abundância de sistemas VCS robustos e disponíveis gratuitamente, Git sendo o melhor exemplo .

Caso contrário, deixe o VCS ser seu arquivo e distribuidor de código. Se outro desenvolvedor quiser examinar o seu código, envie-lhe um e-mail com as diferenças e deixe-o aplicar o que deseja diretamente. Em qualquer caso, a fusão não importa por que ou como a codificação de dois arquivos divergiu.

Por ser um código, o tecido cicatricial pode distrair mais até do que um comentário bem escrito. Por sua própria natureza como código, você faz o programador de manutenção gastar ciclos de CPU mentais para descobrir se o tecido cicatricial tem algo a ver com suas alterações. Não importa se a cicatriz tem uma semana ou 10 anos, deixar tecido cicatricial no código impõe um fardo sobre aqueles que precisam decifrar o código posteriormente.

[EDIT] Eu acrescentaria que existem dois cenários principais que precisam ser distinguidos:

  • desenvolvimento privado, seja codificando um projeto pessoal ou fazendo check-in em uma agência privada
  • Desenvolvimento de manutenção, onde o código que está sendo verificado se destina a ser colocado em produção.

Basta dizer "NÃO" ao tecido cicatricial!


-1 O código comentado é muito útil para entender a intenção de uma função. Em um mundo perfeito, todos deixam ótimos comentários para isso. Mas, no mundo real, descobri que o código comentado é muito útil, e Andrew Shelansky apontou os motivos pelos quais prefiro não ter de procurá-lo no controle de origem.
Brandon Moore

0

Não sei - sempre comento as linhas originais antes de fazer alterações - isso me ajuda a revertê-las se eu mudar de ideia. E sim, eu faço o check-in.

No entanto, retiro qualquer código comentado antigo do check-in anterior.

Eu sei que poderia olhar os logs de diff para ver o que mudou, mas é uma dor - é bom ver as últimas alterações ali mesmo no código.


1
Talvez você precise de melhores ferramentas de comparação?
jw.

Uma razão para não fazer isso seria para que você pudesse ver quem escreveu a linha original trivialmente (por exemplo, git blame)
gtd

Caramba. Para mim, isso seria análogo a dizer "Eu sempre dou descarga antes de usar o banheiro. Mas não depois."
benjismith de

0

Um bom compromisso é escrever uma pequena ferramenta que despeja seus arquivos retirados / modificados em uma unidade de backup de rede. Dessa forma, você pode modificar o conteúdo do seu coração e ter seu trabalho de backup, mas você nunca tem que verificar o código experimental ou inacabado.


0

Acho que fazer check-in do código comentado deve ser válido porque, só porque a nova alteração passou nos testes, pode ser mais útil ver o que estava lá antes e ver se a nova alteração é realmente uma melhoria.

Se eu tivesse que voltar várias versões para ver uma mudança anterior que agora leva a uma queda de desempenho, isso seria muito chato.

Às vezes, o código comentado é um bom histórico, mas coloque datas de quando o código foi comentado. Mais tarde, alguém que esteja trabalhando perto de lá pode simplesmente excluir o código comentado, pois foi provado que ele não é necessário.

Também seria bom saber quem comentou esse código para que, se alguma justificativa for necessária, eles possam ser questionados.

Eu prefiro escrever uma nova funcionalidade, garantir que os testes de unidade sejam aprovados, fazer o check-in e permitir que outros a usem e ver como funciona.


Se você tiver uma equipe inteira desenvolvendo e mantendo o código dessa maneira, ele rapidamente se tornará ilegível. Com o sistema de controle de versão correto, você pode facilmente encontrar diferenças entre versões arbitrárias.
Eddie

0

Se o desenvolvedor comentou algum código porque ele ainda não está completo, a maneira correta de "controle de origem" para lidar com isso seria mantê-lo em um branch separado, até que o código esteja pronto para verificar no.

Com um DVCS (como git, bazaar ou mercurial), isso é muito fácil, pois não requer alterações no repositório central. Caso contrário, talvez você possa falar sobre dar aos desenvolvedores seus próprios branches no servidor se eles estiverem trabalhando em recursos específicos que irão demorar bastante (ou seja, dias).

Não há nada de errado em fazer check-in do código comentado em algumas situações, é apenas que esta é uma situação em que pode haver uma maneira melhor de fazer isso, para que o desenvolvedor possa rastrear as alterações em sua fonte mesmo que não esteja pronto para ser fez check-in no repositório principal.


0

Claramente, o desenvolvedor que está fazendo check-in do código comentado deve estar trabalhando em um branch separado, mesclando as alterações do branch do tronco conforme necessário.

Cabe ao sistema VCS auxiliar o desenvolvedor neste fluxo de trabalho (git é um excelente sistema VCS que funciona muito bem com isso).

Ao utilizar nosso site, você reconhece que leu e compreendeu nossa Política de Cookies e nossa Política de Privacidade.
Licensed under cc by-sa 3.0 with attribution required.