it-swarm.dev

Unterschreiben Sie jede Ihrer Quelldateien mit Ihrem Namen?

Mögliches Duplikat:
Wie verfolgen Sie die Autoren des Codes?

Einer meiner Kollegen hat die Angewohnheit, seinen Namen und seine E-Mail-Adresse als Autoren-Metadaten in den Kopf jeder Quelldatei zu setzen, an der er arbeitet. Ich bin nicht; Ich verlasse mich lieber auf die Quellcodeverwaltung, um zu erfahren, mit wem ich über einen bestimmten Satz von Funktionen sprechen soll.

Sollte ich auch Dateien signieren, an denen ich aus anderen Gründen arbeite? Machst du? Wenn ja warum?

Dies gilt zusätzlich zu den Metadaten für Copyright- und Lizenzinformationen und gilt sowohl für Open-Source- als auch für proprietären Code.

50
regularfry

Nicht wirklich, nein. Dafür gibt es mehrere Gründe:

  • Ihr Versionskontrollsystem (VCS) speichert diese Metadaten bereits. Z.B. Jedes Commit in Git hat ein Feld für den Namen, der das Commit durchgeführt hat. Mit kompetenten Versionskontrollsystemen können Sie auch sehen, wer eine Änderung an bestimmten Codezeilen vorgenommen hat. Diese Funktionalität wird normalerweise als blame bezeichnet, was eine falsche Bezeichnung ist, da sie am nützlichsten ist, anstatt jemanden zu finden, der tatsächlich beschuldigt jemanden finden, mit dem Sie über ein Problem sprechen können, das Sie im Zusammenhang mit dem Code haben).

    Ich habe einige Header-Kommentare gesehen, die ebenfalls ein Verlaufsprotokoll enthalten, die aber auch problemlos aus einem VCS extrahiert werden können.

  • Es entmutigt die Zusammenarbeit mit Code. "Hey, jemand hat das gemacht ... vielleicht sollten wir seinen Code nicht berühren". Wenn für eine Quellcodedatei kein alleiniger Codebesitz besteht, ist die Wahrscheinlichkeit höher, dass jemand anderes sie ändert, was wiederum das Refactoring erleichtert und ermöglicht.

Was ist mit Copyright-Hinweisen?

Aus Gründen des Urheberrechts möchten Sie möglicherweise den Firmennamen als Urheberrechtsinhaber in die Kopfzeilenkommentare einfügen (auch bekannt als Copyright-Banner). Wenn es sich um ein Open Source-Projekt handelt, ist dies häufig der Name der Betreuerorganisation oder stattdessen nur ein Betreuer. Es ist jedoch mittlerweile üblich, diese Informationen in Textdateien im Stammverzeichnis des Projekts abzulegen. Sie können diese Textdateien in Open Source-Projekten mit Namen wie README, LICENSE und/oder CONTRIBUTORS sehen.

Was ist mit Datenbankskripten?

Sie könnten argumentieren, dass Sie Verlaufsprotokolle in Header-Kommentaren mit Datenbank-SQL-Skripten erstellen müssen, obwohl dies in letzter Zeit mit Datenbankmigrationstools zu einer veralteten Praxis geworden ist. Datenbankmigrationstools verfolgen normalerweise, welche Migrationen ausgeführt wurden, und können bei Bedarf Rollbacks durchführen. Diese Tools sind flexibler zu verwenden als eine Textdatei.

77
Spoike

Ich mache das nicht, speziell wie Sie sagten, weil es in der Quellcodeverwaltung verfolgt wird. Jedes Mal, wenn Informationen wie diese an zwei Orten aufbewahrt werden (Quellcodeverwaltung und die Datei selbst, wie Sie sagten), werden sie nicht mehr synchron. Da die Quellcodeverwaltung die Informationen automatisch hinzufügt, gibt es meines Erachtens keinen Grund, sie direkt einzuschließen.

Abgesehen davon, wenn es etwas gibt, das nicht offensichtlich ist, das Sie hinzufügen, oder das eine weitere Diskussion rechtfertigt, lohnt es sich meiner Meinung nach, Kommentare um einen Codeblock hinzuzufügen, die die vorgenommene Änderung und den Grund mit Ihrem Namen angeben.

23
Shawn D.

Ja, ich unterschreibe meinen Code. Ich bin stolz darauf, qualitativ hochwertige Arbeit zu leisten.

16
Paul Nathan

Sollte ich auch Dateien signieren, an denen ich aus anderen Gründen arbeite? Machst du? Wenn ja warum?

Es gibt einen Grund, Ihren Namen in Ihre Dateien aufzunehmen. Das Buch "The Pragmatic Programmer" ermutigt es, weil die Autoren davon ausgehen, dass Sie besseren Code schreiben, wenn Ihr Name darauf geschrieben ist, damit Sie stolz auf Ihre Arbeit sein können. Programmierer würden keine unordentlichen Codeteile signieren wollen, oder?

Hier trifft die Realität. Meistens, nur der Erstautor ist in den Dateien und wie andere hier angegeben, werden diese Informationen bald nicht mehr synchron sein. Und es verhindert keinen unordentlichen Code. Die meisten ignorieren Sie einfach die Tatsache, dass ihr Name im Header der Datei aufgeführt ist. Dies ist überhaupt kein sehr pragmatischer Ratschlag aus einem ansonsten ausgezeichneten Buch, obwohl es für manche Menschen einen Unterschied machen kann.

Ein weiterer Grund, Ihren Namen in den Dateien zu behalten, besteht darin, dass Sie Quellcode veröffentlichen möchten, beispielsweise für ein Open Source-Projekt. Dies kann als eine Art Werbung angesehen werden.

Aber in den meisten Fällen handelt es sich bei dieser Information lediglich um redundantes Rauschen.

14
Falcon

git blame (oder svn blame wenn Sie müssen) ist ein viel besseres Werkzeug zum Ableiten von Code "Besitz" als ein Einzeiler am Anfang einer Datei, insbesondere nachdem ein Projekt einige Whisker gewachsen ist.

11
Dan Ray

Warum möchten Sie einen Kommentar mit dem Namen einer Person in Ihrem Quellcode?

Wenn es keinen Einblick in die Absicht des Codes gibt und es nicht möglich ist, sich an Ihren eigenen Namen zu erinnern, hat das überhaupt keinen Wert, den ich sehen kann.

Es würde beim nächsten Commit entfernt werden, wenn ich darauf stoßen würde.

Natürlich sind Kommentare im Allgemeinen ein Geruch für sich, aber das ist ein anderes Thema :)

6
Chris Lee

Nein, ich nicht. Alle vorgeschriebenen Header (ein bestimmter Header-Kommentar nach Unternehmensstandard ist Teil der Richtlinien für den Codierungsstil) sind enthalten. Wenn sie dies als Teil von ihnen erfordern, würde ich dies tun. Wenn Sie keine Projekt-, Programm- oder Unternehmenscodierungsstile haben, sollten Sie dies tun, und alle vorgeschriebenen Dateikopfkommentare sollten klar definiert sein.

Wie Sie sagten, sollte die Versionskontrolle dies verwalten. Wenn andere Personen die Datei berühren, sollen sie ein Feld aktualisieren, das bereits automatisch von der Versionskontrolle verfolgt wird und das genau angibt, was geändert wurde und wer die Änderung zwischen den einzelnen Versionen vorgenommen hat? Das scheint nur ein Overhead zu sein, insbesondere wenn ein Entwickler vergisst, dies zu aktualisieren, und zukünftige Entwickler den Header verwenden, anstatt sich um die Versionskontrolle zu kümmern.

5
Thomas Owens

Ich mache. Der Grund ist nicht, dass ich es irgendwie "besitzen" möchte, indem ich meinen Namen darauf schreibe. Wenn jemand diese Zeile bearbeiten wollte, könnte es mich weniger interessieren. Und zu sagen, dass die Versionskontrolle meine Daten speichert, ist wahr und dennoch sinnlos, wenn jemand keinen Zugriff auf mein Repo hat.

Ich arbeite für ein großes Unternehmen und mein Code wandert von Geschäftseinheit zu Geschäftseinheit. Der arme Trottel, der den Code von einem Kerl bekommt, der ihn von einem anderen Kerl bekommen hat, der ihn von meinem idiotischen Chef bekommen hat, wird nicht die geringste Ahnung haben, wen er um Unterstützung bitten soll, es sei denn, ich hinterlasse einen Hinweis im Code selbst.

Und weil ich nicht erwarte, für immer hier zu bleiben, hinterlasse ich echte Kontaktinformationen, damit die Leute mich kontaktieren können, nachdem ich meinen aktuellen Job verlassen habe, wenn sie etwas brauchen. Es ist nur Höflichkeit.

5
Satanicpuppy

My IDE setzt beim Erstellen einer neuen Klasse automatisch Benutzernamen an die Spitze der Dateien. Das ist eigentlich ärgerlich, weil wir diesen Header einfach ignorieren.

hm, vielleicht sollten wir einen neuen Codierungsstandard einführen, bei dem jeder dies in den Einstellungen seines IDE] deaktivieren und/oder den automatischen Header löschen muss ...

4
jhocking

In meiner Firma verwenden wir einen standardisierten Header mit einem Copyright-Hinweis für unseren Firmennamen und Schlüsselfeldern für die Versionskontrolle, wie Revision, Datum, ID

3
oenone

Es ist für uns Standard, unseren Namen in den Quellcode einzufügen und diese Änderungen, wenn wir sie ändern, zusätzlich mit einer Änderungsnummer und unserem Namen gegen diese Änderungsnummer zu kennzeichnen.

TBH, das ist die Art von Dingen, die ich in internen Codierungsstandards erwartet hätte.

1
temptar

Ich bin sicher, ich werde hier negative Punkte bekommen.

Ich platziere meinen Namen in Dateien, die ich erstellt habe. Ich füge auch den Firmennamen und die Adresse, eine Copyright-Erklärung, eine Beschreibung des Zwecks der Datei, den ursprünglichen Namen der Datei (in der Datei) und eine kurze Historie wichtiger Revisionen hinzu.

Warum mache ich das:

  1. Der Firmenname, die Adresse und die Copyright-Erklärung machen es sehr einfach, vor Gericht zu produzieren, falls dies jemals erforderlich sein sollte, und das Datum/die Uhrzeit der Erstellung, das Eigentum usw. zum Zwecke des Urheberrechts anzugeben. Ohne diese Informationen IN DER DATEI verlassen Sie sich auf Rauch und Spiegel, um einen Richter zu überzeugen, der nichts über Software oder VCS weiß.

  2. Bei der Eingabe des ursprünglichen Autorennamens zum Zeitpunkt der Erstellung geht es um Verantwortlichkeit. Wenn Ihr VCS die gleichen Informationen liefert, ist das schön, aber es ist nicht in Ihrem Gesicht. Wenn das Ding später geändert wird und jemand Fehler hinzufügt, erzählt das VCS die Geschichte. Wenn Sie stolz auf Ihre Arbeit sind, verstecken Sie sich nicht. [Eine Reihe von Handelsunternehmen verlangen solche Dinge auch aus Gründen der reinen Rechenschaftspflicht.]

  3. Ich habe den Namen der Datei in die Datei eingefügt, weil sich diese Dinge ändern. Es ist ein Schmerz, dies zu aktualisieren, wenn sich der Name ändert, und ich bin mir des Werts nicht mehr sicher. Es hilft jedoch, das gesamte Bild zusammenzustellen, wenn Sie die Quelle betrachten.

  4. Jede Datei hat eine Zusammenfassung in einem oder zwei Absätzen ihres Zwecks. Wenn eine Quelldatei keinen Zweck hat, erstellen Sie sie nicht. Wenn es einen Zweck hat, sag mir, was das ist - lass mich nicht raten. Ungefähr 95% des gesamten Open-Source-Codes, auf den ich stoße, haben keinen in den Quelldateien angegebenen Zweck, und das macht mich verrückt. Ich möchte den Zweck des Dateinamens oder des Inhalts nicht erraten, um laut zu schreien - sag es mir. Nicht einen Zweck zu setzen ist einfach Faulheit. (Und den Zweck nicht zu aktualisieren ist auch Faulheit.)

  5. Vor VCS habe ich zu Beginn einen vollständigen Verlauf in die Kommentare eingefügt. Post VCS Ich habe das auch eine Weile gemacht. Es zeigt den Verlauf in der Datei, ohne irgendwo anders graben zu müssen. Es ist jedoch ein Schmerz also tu dies und ein niedriger Wert. Verwenden Sie dazu Ihren VCS-Verlauf. Wenn Sie jedoch in den Kopfzeilen eine größere Änderung vornehmen (umfangreiches Refactoring, Umnutzung usw.), machen Sie sich eine Notiz zum Nutzen anderer. (Und wie der ursprüngliche Autor, geben Sie Ihren Namen ein.) Es ist natürlich ein Urteil darüber, was wichtig ist und was nicht. Aber dies ist eine Höflichkeit für diejenigen, die nach dir kommen.

Ich habe auch umfangreiche Kommentare in der Datei, die darlegen, was zu tun ist - Kommentare, zum Beispiel zu Schnittstellen, APIs, Headern, sind für einen Benutzer Ihrer API oder Funktion oder Methode unerlässlich, um zu wissen, was vor sich geht, und insbesondere spezielle Hinweise oder Nebenwirkungen.

Innerhalb des Codes erhalten Hauptblöcke einen Kommentar, der beschreibt, was dieser Block tut. Dies ermöglicht ein schnelles Lesen des Codes für Absichten, ohne dass Sie sich mit den Details einer Variablen befassen müssen, die 15 Seiten zuvor deklariert wurde. (Sag mir was es tut und warum. Sag mir nicht wie. Ich kann das Wie aus dem Code herausfinden.)

Basierend auf dem, was ich von anderen sehe, die hier Kommentare hinterlassen, scheinen viele von ihnen etwa 90% der von mir geschriebenen Kommentare zu löschen. Schade ... trägt zur Entropie des Universums bei.

0
quickly_now

Ich denke, es ist keine so schlechte Angewohnheit.

Andere argumentieren, dass VCS das für Sie tun wird. Nun, bis zu einem gewissen Punkt ist das wahr.

Wenn Sie jedoch Code unter einem schwachen Copyleft (MIT oder was auch immer) veröffentlichen, können Sie fast wetten, dass jemand einen Schnappschuss Ihres Codes in seine Codebasis integriert und seine eigenen Änderungen vornimmt. Sie können den Unterschied zwischen den ursprünglichen Kommentaren und den Kommentaren der Person, die den ursprünglichen Check-in vorgenommen hat, nicht erkennen.

Gleiches gilt, wenn Codebasen auf andere VCSs verschoben werden (z. B. von CVS auf git). Sie können nicht wirklich sagen, ob all diese Metadaten in das neue VCS gelangen (ich würde erwarten, dass es eine Möglichkeit gibt, es zu migrieren).

Um die Frage zu beantworten:

Wenn es einen erheblichen Mehrwert bietet, den Autor eines Codeteils zu kennen (was nicht immer der Fall ist), ist es eine gute Idee, den Autor direkt in die Quelldatei einzufügen. Das bedeutet nicht, dass Sie jede einzelne Änderung, die Sie an einer Quelldatei vornehmen, dokumentieren und signieren sollten.

0
back2dos