Você assina cada um dos seus arquivos de origem com o seu nome? [duplicado]

49

Um de meus colegas tem o hábito de colocar seu nome e endereço de e-mail na cabeça de cada arquivo de origem em que ele trabalha, como metadados do autor. Eu não sou; Eu prefiro confiar no controle de origem para me dizer com quem eu devo falar sobre um determinado conjunto de funcionalidades.

Devo também assinar arquivos em que trabalho por outros motivos? Você? Se sim, por quê?

Para ser claro, isso é um acréscimo aos metadados para informações de direitos autorais e licenciamento incluídos e se aplica tanto a código aberto quanto a código proprietário.

    
por regularfry 17.08.2011 / 16:12
fonte

14 respostas

76

Não é verdade, não. Existem algumas razões para isso:

  • Seu sistema de controle de versão (VCS) armazena esses metadados já . Por exemplo. cada commit no git tem um campo para o nome que fez o commit. Os sistemas de controle de versão competentes permitem que você veja quem fez uma alteração em linhas de código específicas também. Essa funcionalidade é geralmente chamada de blame , o que é um equívoco, pois, em vez de encontrar alguém para fazer uma acusação real, é mais útil para encontrar alguém para conversar sobre um problema que você tem no contexto de o pedaço de código).

    Eu já vi alguns comentários de cabeçalho que também têm histórico, mas que também podem ser facilmente extraídos de um VCS.

  • Desencoraja a colaboração de código . "Ei, alguém fez isso ... talvez não devêssemos tocar no código dele". Se não houver propriedade exclusiva de código em algum arquivo de código-fonte, maior a chance de outra pessoa alterá-lo, o que, por sua vez, facilita e ativa a refatoração.

E os avisos de direitos autorais?

Embora, por causa dos direitos autorais, você queira adicionar o nome da empresa como titular dos direitos autorais nos comentários do cabeçalho (também conhecido como banner de direitos autorais). Se for um projeto de código aberto, geralmente é o nome da organização do mantenedor ou apenas um mantenedor. No entanto, agora é prática comum colocar essas informações em arquivos de texto na raiz do projeto. Você pode ver esses arquivos de texto em projetos de código aberto com nomes como README , LICENSE e / ou CONTRIBUTORS .

E os scripts de banco de dados?

Você poderia argumentar que precisa fazer logs de histórico em comentários de cabeçalho com scripts SQL de banco de dados, embora ultimamente com ferramentas de migração de banco de dados tenha tornado isso uma prática obsoleta. As ferramentas de migração de banco de dados geralmente acompanham quais migrações foram executadas e podem fazer rollbacks conforme necessário. Essas ferramentas são mais flexíveis de usar do que um arquivo de texto.

    
por 17.08.2011 / 16:21
fonte
23

Eu não faço isso, especificamente como você disse, porque ele é rastreado no controle de origem. Sempre que informações como essa forem mantidas em dois lugares (controle de origem e o próprio arquivo, como você disse), elas ficarão fora de sincronia . Como o controle de origem adiciona automaticamente as informações, não acho que haja motivos para incluí-las diretamente.

Dito isso, se há algo não óbvio que você está adicionando, ou pode justificar uma discussão mais aprofundada, acho que vale a pena adicionar comentários em torno de um bloco de código indicando a alteração feita e por que com seu nome.

    
por 17.08.2011 / 16:19
fonte
15

Sim, assino meu código. Tenho orgulho em produzir um trabalho de qualidade.

    
por 18.08.2011 / 00:02
fonte
14

Should I also be signing files I work on for any other reasons? Do you? If so, why?

Existe um motivo para colocar o seu nome nos seus arquivos. O livro "O Programador Pragmático" o encoraja, porque os autores assumem que você escreverá um código melhor quando seu nome estiver escrito nele, para que você possa se orgulhar de seu trabalho. Os programadores não gostariam de assinar pedaços confusos de código, não é?

Bem, aqui é onde a realidade ataca. Na maioria das vezes , apenas o autor inicial está nos arquivos e, como os outros aqui afirmaram, esta informação estará fora de sincronia em breve. E isso não impede o código confuso. A maioria simplesmente ignora o fato de que seu nome está listado no cabeçalho do arquivo. Este não é um conselho muito pragmático, de um livro excelente, embora para algumas pessoas isso possa fazer a diferença.

Outro motivo para manter seu nome nos arquivos é quando você deseja publicar o código-fonte, por exemplo, para um projeto de código aberto. Isso pode ser visto como algum tipo de anúncio.

Mas em mais casos, essa informação é apenas ruído redundante.

    
por 17.08.2011 / 16:35
fonte
9

git blame (ou svn blame , se necessário) é uma ferramenta muito melhor para deduzir a "propriedade" de código do que uma linha no topo de um arquivo, especialmente depois que um projeto cresceu alguns bigodes.

    
por 17.08.2011 / 16:34
fonte
5

Não, não sei. No entanto, quaisquer cabeçalhos obrigatórios (um comentário de cabeçalho padrão da empresa em particular faz parte das diretrizes de estilo de codificação) são incluídos, portanto, se eles exigirem isso como parte deles, eu o faria. Se você não tem projetos, programas ou estilos de codificação corporativa, então você deve, e qualquer comentário de cabeçalho de arquivo obrigatório deve ser claramente definido.

Como você disse, o controle de versão deve estar gerenciando isso. Quando outras pessoas tocam no arquivo, elas devem atualizar um campo que já foi rastreado automaticamente pelo controle de versão, que identifica exatamente o que foi alterado e quem fez a alteração entre cada versão? Isso parece uma sobrecarga, especialmente se um desenvolvedor esquecer de atualizar isso e futuros desenvolvedores passarem pelo cabeçalho, em vez de procurar no controle de versão.

    
por 17.08.2011 / 16:17
fonte
5

eu faço. A razão não é porque eu quero "possuí-la" de alguma forma, colocando meu nome nela. Se alguém quisesse editar essa linha, eu poderia me importar menos. E dizer que o controle de versão armazenará meus dados é verdadeiro e, no entanto, inútil se alguém não tiver acesso ao meu repositório.

Eu trabalho para uma grande corporação e meu código vagueia de unidade de negócios para unidade de negócios. O pobre idiota que pega o código de um cara, que o pegou de outro cara, que recebeu do meu chefe idiota, não vai ter a menor idéia de quem pedir apoio a menos que eu deixe uma sugestão no próprio código.

E, como não espero ficar aqui para sempre, deixo as informações de contato real , para que as pessoas possam entrar em contato comigo depois que eu deixar meu trabalho atual, se precisarem de algo. É só cortesia.

    
por 17.08.2011 / 21:37
fonte
5

Por que você quer um comentário com o nome de alguém em seu código-fonte?

Se você não souber entender o objetivo do código e se não se esforçar para lembrar o seu próprio nome, não há nenhum valor que eu possa ver.

Seria removido no próximo commit se eu encontrasse.

Claro, os comentários geralmente são um cheiro em si, mas isso é outro tópico:)

    
por 25.08.2011 / 08:25
fonte
4

Meu IDE coloca nomes de usuário automaticamente no topo dos arquivos quando você cria uma nova classe. É meio chato na verdade, porque simplesmente ignoramos esse cabeçalho.

hm, talvez devêssemos instituir um novo padrão de codificação em que todos tenham que desativar isso nas preferências de seu IDE e / ou excluir o cabeçalho automático ...

    
por 17.08.2011 / 16:38
fonte
3

Na minha empresa, usamos um cabeçalho padronizado com uma nota de direitos autorais para o nome da empresa e keyfields para o controle de versão, como Revisão, Data, Id

    
por 17.08.2011 / 16:35
fonte
1

É padrão para nós colocar nosso nome no código-fonte e, adicionalmente, se modificá-lo, marcar essas alterações com um número de alteração e nosso nome em relação a esse número de alteração.

TBH, esse é o tipo de coisa que eu esperaria ver nos padrões internos de codificação.

    
por 17.08.2011 / 16:15
fonte
0

Eu acho que não é um hábito tão ruim.

Outros argumentam que o VCS fará isso por você. Bem, até certo ponto, isso é verdade.

Se você liberar código sob um copyleft fraco (MIT ou qualquer outro), você pode quase apostar, que alguém integrará um snapshot de seu código em sua base de código e fará suas próprias modificações. Eles não poderão dizer a diferença entre os comentários originais e os comentários da pessoa que fez o check-in original.

A mesma coisa se aplica quando as bases de código se movem para outros VCSs (por exemplo, do CVS para o git). Você não pode realmente dizer se todos os metadados serão incluídos no novo VCS (eu esperaria que houvesse alguma maneira de migrá-lo).

Então, para responder à pergunta:

Quando ele agrega valor significativo para conhecer o autor de um trecho de código (o que nem sempre é o caso), é melhor adicionar o autor diretamente no arquivo de origem. Isso não significa que você deve documentar e assinar todas as alterações feitas em um arquivo de origem.

    
por 25.08.2011 / 14:46
fonte
0

Tenho certeza de que vou receber pontos negativos aqui.

Eu coloco meu nome em arquivos que criei. Também incluo o nome e o endereço da empresa, uma declaração de direitos autorais, uma descrição do objetivo do arquivo, o NOME original do arquivo (no arquivo) e um breve histórico das principais revisões.

Por que eu faço isso:

  1. O nome da empresa, o endereço e a declaração de direitos autorais tornam muito fácil a produção em juízo, caso seja necessário, e mostram a data / hora da criação, propriedade etc., para fins de direitos autorais. Sem essa informação, NO ARQUIVO você está contando com fumaça e espelhos para convencer um juiz que não sabe nada sobre software ou VCS.

  2. Colocar o nome do autor original no momento da criação é sobre responsabilidade. Se o seu VCS dá a mesma informação, isso é bom, mas não está na sua cara. Se a coisa for mudada mais tarde e alguém adicionar bugs, o VCS conta a história. Se você está orgulhoso do seu trabalho, não se esconda. [Várias empresas comerciais exigem esse tipo de coisa por motivos simples de responsabilidade também.]

  3. Eu coloquei o nome do arquivo no arquivo porque essas coisas mudam. É um pain para atualizar isso quando o nome mudar, e eu não tenho mais certeza do valor. No entanto, ajuda a juntar toda a imagem quando se olha para a fonte.

  4. Todo arquivo tem um resumo em um parágrafo ou 2 de sua finalidade. Se um arquivo de origem não tiver propósito, não o crie. Se tiver um propósito, diga-me o que é isso - NÃO ME FAÇA GUESS . Cerca de 95% de todo o código-fonte aberto que eu encontro não tem um propósito declarado nos arquivos de origem e isso me deixa louco. Eu não quero adivinhar o propósito do nome do arquivo ou do conteúdo, por chorar em voz alta - me diga. Não colocar um propósito é simplesmente LAZINESS. (E não atualizar o propósito também é preguiça.)

  5. Pré VCS Eu costumava colocar um histórico completo nos comentários no começo. Post VCS Eu fiz isso por um tempo também. Ele mostra o histórico no arquivo sem ter que ir procurar em outro lugar. No entanto, é uma dor , portanto, faça isso e um valor baixo. Use seu histórico de VCS para isso. Mas nos cabeçalhos, se você fizer uma grande mudança (refatoração, re-propósito, etc) - então faça uma anotação para o benefício dos outros. (E como o autor original, coloque em seu nome.) É claro que é um julgamento quanto ao que é importante e o que não é. Mas isso é uma cortesia para aqueles que vêm depois de você.

Eu também tenho extensos comentários no arquivo que definem o que as coisas fazem - comentários por exemplo em interfaces, APIs, cabeçalhos, são essenciais para um usuário de sua API ou função ou método para saber o que está acontecendo, e especialmente qualquer notas especiais ou efeitos colaterais.

Dentro do código, os blocos principais recebem um comentário descrevendo o que esse bloco faz. Isso permite uma leitura do código de intenção, rapidamente, sem ter que cavar os detalhes sangrentos de alguma variável declarada 15 páginas antes. (Diga-me o que faz, e por que . Não me diga como . Eu posso descobrir o como do código.)

Com base no que vejo de outras pessoas deixando comentários aqui, parece que muitos deles eliminariam cerca de 90% dos comentários que escrevo. Vergonha ... aumenta a entropia do universo.

    
por 21.12.2011 / 07:06
fonte
-2

A única razão para colocar seu nome no topo de um arquivo é quando é uma lição de casa e seu professor exige que ele mantenha em linha reta qual aluno escreveu o código que ele está olhando em uma impressão.

    
por 21.12.2011 / 06:05
fonte