Fügen Sie am Anfang jeder .hpp/.cpp-Datei Informationen hinzu?

Question

Wenn Sie eine neue C++ - Header/Quelldatei erstellen, welche Informationen fügen Sie an die Spitze hinzu? Fügen Sie beispielsweise das Datum, Ihren Namen, eine Beschreibung der Datei usw. hinzu? Verwenden Sie für diese Informationen ein strukturiertes Format?

z.B.

// Foo.cpp - Implementation of the Foo class 
// Date: 2008-25-11 
// Created by: John Smith 

Ein Team, das ich weiß, bettet CVS zu Fuß jeder Datei Nachrichten begehen, aber ich bin nicht sicher, ob ich weit dies gehen will ...

Answer 1

Informationen darüber, wer eine Datei erstellt hat und wann und wer sie bearbeitet hat und wann alles in der Quellcodeverwaltung ist. Wenn Ihr Team gute Erfahrungen mit Check-in-Kommentaren hat, werden Sie auch die Gründe für jede Änderung kennen. Keine Kommentare für dieses Zeug.

Ich denke, es ist 100% ig legit - sogar, einen Kommentarblock zu setzen, so lange wie nötig, um den Zweck der Klasse/des Moduls zu erklären. Wenn die nächste Person es ändert, werden sie eine bessere Vorstellung von der Gesamtvision haben und ob diese Datei der geeignete Ort für ihre Veränderung ist.

Einige Geschäfte setzen Copyright-Hinweise und andere rechtliche Folderol in Quelldatei Kommentare. Das erscheint mir nur albern - wenn Ihr (Nicht-OSS-) Quellcode ohne Ihr Wissen oder Ihre Erlaubnis auf die Server von jemand anderem gelangt ist, wird ein Copyright-Hinweis sie wahrscheinlich nicht daran hindern, irgendetwas damit zu tun. IANAL, YMMV.

Answer 2

ich das Datum nicht einbetten, weil es redundant. Wenn jemand wissen möchte, an welchem ​​Datum eine Datei erstellt wurde, traue dem Autor nicht, vertraue deinem Quellcodeverwaltungssystem. Es sollte die definitive Antwort für das Erstellungsdatum sein.

Ich bin definitiv nicht gegen einbetten Einchecken Nachrichten obwohl. Das sind ziemlich nützlich.

Answer 3

Nicht. Die meisten Sachen können bei Bedarf aus dem Versionsverwaltungssystem abgerufen werden, sodass das Hinzufügen überflüssig ist. Das würde Sie mit der Beschreibung des Inhalts der Datei verlassen, aber das ist die meiste Zeit Teil der Klassendokumentation (oder zumindest die Dokumentation des spezifischen Typs).

Ich mache keine von denen, aber andererseits mag ich nicht die Gruft.

Answer 4

Ich füge den Dateinamen, eine kurze Beschreibung des Zwecks der Datei und ein $ Id $ -Tag für CVS oder Subversion Zwecke. Der Ersteller der Datei und das Erstellungsdatum können durch Überprüfung des Repositorys gefunden werden, so dass es nicht benötigt wird.

Der Dateiname ist enthalten, da dies je nach dem, was Sie zum Bearbeiten der Datei verwenden, nicht ganz offensichtlich ist, wenn Sie ihn bearbeiten. Die Beschreibung kann verwendet werden, um zu bestimmen, ob ein Code in die Datei gehört oder ob sie in einen anderen Code verschoben werden soll. Und natürlich gibt $ Id $ Ihnen die letzte Änderungszeit und den letzten Editor.

Das Einbetten von Check-in-Nachrichten ist nur nützlich, wenn die Nachricht nützlich ist, und nur dann, wenn die Datei immer wieder aktualisiert wird. Wenn Sie jede Nachricht einbeziehen, wird die Datei einfach so aufgebläht, dass mehr Kommentare die Änderungen beschreiben als der eigentliche Code. Am besten, dies auch dem Repository zu überlassen; Oft ist es nur eine kurze Befehlszeile, um das Check-in-Protokoll der Datei zu erhalten.

Wenn Sie mit einem Revisionskontrollsystem festgefahren sind, das keine Historie für Bewegungen und Kopien behalten kann, verweisen Sie in diesem Fall nur auf die Originaldatei und ihre Versionsnummer. Natürlich, wenn Sie ein System verwenden, das irgendwann in diesem Jahrhundert erstellt wurde und nicht das letzte, sollte das kein Problem sein.

Answer 5

Wir müssen Copyright-Informationen an den Anfang jeder Datei setzen. Ich denke, Daten, Autoren und der Name der Datei ist Zeitverschwendung.

Wir haben auch unser Quellkontrollsystem append Check-in Kommentaren an den Boden jede Datei. Ich hasste anfangs das Änderungsprotokoll, aber mit der Zeit habe ich gelernt, es zu mögen. Es hilft wirklich beim Zusammenführen von Änderungen.

Answer 6

Wenn Sie CVS verwenden, überprüfen Sie es ist keyword substitutions. Sie werden dabei helfen, diese Informationen einzubetten.

Persönlich halte ich mich dies an der Spitze aller meiner Quelldateien:

// $Id$ 

Weitere informative Kommentare, die ich einbetten mit Doxygen analysiert werden, wenn sie etwas Bestimmtes (die Datei beziehen, die Klasse, ein Typ usw.).

Answer 7

Wir nutzen unsere RCS automatisch auf die Datei die folgende stempeln:

Urheberrecht,

RCS Dateiname,

Datum geändert,

Autor der letzten Änderung,

RCS Revisionsnummer

I denke, das ist sehr praktisch. Ich mag es wirklich, wenn der Dateiname in jeder Datei automatisch ausgefüllt wird, da dies die Suche nach der Lösung für Dateien sehr schnell macht.

Answer 8

i Regel nur hinzufügen, jede „Kommentar info“ wenn ... Ich glaube nicht, ich werde mich daran erinnern oder es ist nicht klar, was etwas oder tut, wenn ich den Quellcode freigeben, und ich will wirklich andere in der Lage zu sein/davon zu lernen.

Answer 9

Ich füge normalerweise eine Beschreibung des Zwecks des Codes ein, der in dieser Datei gefunden wird. Alles andere scheint an anderer Stelle behandelt werden: Daten und Hinweise in der Quellcodeverwaltung usw.

Answer 10

Ursprünglich hier beantwortet, aber da gestrichen: 134249

Ich würde setzen nur zwei Dinge:

• Lizenzierung/copyright Informationen
• Kommentare von Dokumentation-erzeugenden Tools erforderlich (dh die Kommentare müssen in der Kopfzeile zu arbeiten sein - andernfalls sollten sie in den Definitionsdateien gehen)

Alles andere ist unnötig Flusen, die nicht beibehalten werden, und wird schließlich schlimmer als gar nichts werden.

Damals arbeitete ich für eine große Rüstungsfirma, und wir hatten drakonische Kodierungsstandards.Wenn Sie ihnen bis zum Buchstaben folgen (und die meisten Leute nicht), würden die meisten Ihrer Überschriften hauptsächlich von diesem sinnlosen Flaum bestehen. Doppelt schlimmer ist, dass der gleiche Flaum auch in den Quelldateien gespeichert werden muss, was bedeutet, dass zwei Kopien des Flaums veraltet sind und irreführend werden.

Answer 11

Jeder sagt, dass Ihre Quellcodeverwaltung das Datum und die Programmiererinformationen hat, aber das stimmt nicht immer. Ich arbeitete in einem Geschäft, das Source Safe verwendete, und es war in Ordnung, bis jemand beschloss, eine Datei an einen anderen Ort zu verschieben. Zu diesem Zeitpunkt wurde es im Wesentlichen eine neue Datei nach SS, und keine vorherige Geschichte existierte.

Vielleicht wurden daher der Name und das Datum des Programmierers automatisch zum Kommentarbereich am Anfang der Datei hinzugefügt. Wenn es mehr als etwa 10 Einträge geben sollte, würden wir alle mittleren entfernen und nur das ursprüngliche Datum und den Autor sowie die aktuellen Informationen zurücklassen.

Answer 12

Eine Copyright-Erklärung für meine Kunden ;-)

Answer 13

Das ist, was ich normalerweise an der Spitze der Dateien setzen:

///////////// Copyright © 2008 DesuraNET. All rights reserved. ///////////// 
// 
// Project  : [project name] 
// File  : [file name] 
// Description : 
//  [TODO: Write the purpose of ... ] 
// 
// Created On: 11/12/2008 2:24:07 PM 
// Created By: [name] <mailto:[email]> 
//////////////////////////////////////////////////////////////////////////// 

und ich einen Makro in vis, um es zu tun fügen in und fülle die Standardinfo aus, wenn ich eine neue Datei anlege

Answer 14

Wir verwenden MSVC & VSS und haben ein Plugin, das jeden Kommentar, den du beim Einchecken angegeben hast, zu der Datei hinzufügt, die als Kommentar eingecheckt wird. Es ist sehr praktisch, den oberen Teil der CPP-Datei zu betrachten, um die Fehlerverfolgungs-Ticketnummer zu ermitteln, für die eine Änderung vorgenommen wurde.

Answer 15

Ich mochte es, Versionskontrollschlüsselwörter in den Header der Datei zu setzen. Aber von dieser Krankheit erholt. :) Aus zwei Gründen:

1. Niemand hat Kommentare eingefügt, die von Nutzen sind. Sie sehen sich immer die Diffs an, die vom Versionskontrollsystem gemeldet werden.
2. Es entsteht ein Albtraum beim Versuch, große Dateigruppen zu unterscheiden, da die Schlüsselwörter Unterschiede verursachen, die den einzigen Unterschied in der Datei darstellen.

Answer 16

Ich benutze Subversion. Hier ist, was ich gerne an die Spitze setze.

Das ersetzt die Revision, den letzten Editor und dann den Speicherort der Datei im Repository. Obwohl ich immer von Arbeitskopien aus arbeite, kann ich eine Datei drucken/mailen und sie später ansehen, um genau zu wissen, woher sie kommt. $HeadURL$ ist besonders nett, weil es sagt, in welchem ​​Projekt und in welcher Verzweigung die Datei ist und wie man dazu kommt (nett mit größeren verschachtelten Unterpaketen und ähnlichem).

Einverstanden auf die Unbrauchbarkeit der großen manuellen Kommentarblöcke — obwohl Docstrings/Javadocs — empfohlen werden und beim Anhängen automatisch das Commit-Protokoll.

Es klingt wie einige von Ihnen schreckliche VCSes verwenden, wenn Sie Diffs erhalten oder Konflikte durch die Schlüsselwörter selbst zusammenführen. Subversion handles it well.