Wie soll ich meinen Code für OpenSourcing vorbereiten und auf GitHub stellen?

In ein paar Wochen ist mein Projekt abgeschlossen und ich möchte meinen Code für andere Benutzer bereitstellen.

Ich werde alles auf GitHub veröffentlichen, damit die Leute es optimieren und hoffentlich verbessern können.

Ich denke, was ich frage, ist, wie ich am besten sicherstellen kann, dass mein Code ausreichend dokumentiert und richtig formuliert ist, damit andere ihn verwenden können.

Ich weiß, dass Sie immer alles kommentieren sollten und ich werde die @ params-Funktion für jede Methode einfügen, aber gibt es generell noch andere Tipps?

• Stellen Sie sicher, dass sich im Stammverzeichnis des Repositorys eine README.txt-Datei befindet, die auf Anweisungen zum Erstellen verweist. Die Anweisungen können sich in dieser Datei oder in einer separaten Datei oder Wiki-Seite befinden.
• Stellen Sie es im Idealfall so ein, dass Sie den Code mit einem einzigen Befehl vollständig erstellen und testen können. Benötigen Sie keine manuellen Schritte.
• Stellen Sie sicher, dass Sie Tests für den Code haben. Dies bietet anderen Entwicklern einen bequemen Ort, um zu sehen, wie Ihr Code verwendet wird, und bietet ein Sicherheitsnetz für Personen, die Ihren Code ändern. Zu wissen, dass ich Ihren Code bearbeiten und dann eine Suite ausführen kann, um festzustellen, ob ich etwas kaputt gemacht habe, ist von unschätzbarem Wert.
• Befolgen Sie die gängigen Codierungsstandards oder veröffentlichen Sie die von Ihnen verwendeten.
• Wenn Ihr Code OO verwendet, stellen Sie sicher, dass mindestens alle öffentlichen Methoden und Attribute über eine ausreichende Dokumentation verfügen
• Stellen Sie sicher, dass klar ist, welche Lizenz Ihr Code verwendet. In der Regel bedeutet dies, eine LICENSE.txt-Datei einzuschließen oder den für Ihre spezifische Lizenz erforderlichen Mechanismus zu befolgen. Treffen Sie auch eine bewusste Entscheidung über die Lizenz. Verwenden Sie nicht nur GPL, denn das ist alles, was Sie wissen. Verwenden Sie BSD, MIT oder Apache nicht nur, wenn Sie damit vertraut sind. Nehmen Sie sich eine Stunde Zeit, um diese zu untersuchen, damit Sie zumindest den grundlegenden Unterschied zwischen GPL- und Nicht-GPL-Lizenzen verstehen.
• Entfernen Sie alle vertraulichen Informationen aus dem Code, z. B. fest codierte Benutzernamen, Kennwörter, E-Mail-Adressen, IP-Adressen, API-Schlüssel usw. (danke an Hakan Deryal für den Vorschlag).

Die Dokumentation in der Quelldatei ist immer gut, aber Sie sollten zusätzliche Dokumentation auf einer Website veröffentlichen. Erklären Sie das Ziel, die Funktionsweise, Ihre Zukunftspläne, versuchen Sie, den Beitrag zu vereinfachen (andernfalls ... niemand wird Ihnen helfen), und stellen Sie einige Tutorials bereit.

Der Versuch, an einem Projekt nur mit Quellcodedokumentation zu arbeiten, ist immer frustrierend.

Ich denke, was ich frage, ist, wie ich am besten sicherstellen kann, dass mein Code ausreichend dokumentiert und richtig formuliert ist, damit andere ihn verwenden können.

Als Open Source sind die wichtigsten Kommentare der Kommentar zu Urheberrechten und Lizenzvereinbarungen. Anstelle eines großen langen Kommentars am Anfang jeder Datei möchten Sie möglicherweise einen kurzen und süßen Kommentar verwenden, der das Urheberrecht kurz angibt und den Leser auf die Datei license.txt im Stammverzeichnis verweist.

Ich weiß, dass Sie immer alles kommentieren sollten und ich werde die @ params-Funktion für jede Methode einfügen, aber gibt es generell noch andere Tipps?

Alles kommentieren? Kommentieren Sie den Code, der wirklich kommentiert werden muss. Kommentar sparsam. Welche der folgenden beiden Versionen einer Klassendefinition möchten Sie als potenzieller Benutzer eines Codeabschnitts lieber sehen?

Version A:

class Foo {
private:
   SomeType some_name; //!< State machine state

public:
   ...

   /**
    * Get the some_name data member.
    * @return Value of the some_name data member.
    */
   SomeType get_some_name () const { return some_name; }

   ...
};

Version B:

/**
 * A big long comment that describes the class. This class header comment is very
 * important, but also is the most overlooked. The class is not self-documenting.
 * Why is that class here? Your comments inside the class will say what individual parts
 * do, but not what the class as a whole does. For a class, the whole is, or should be,
 * greater than the parts. Do not forget to write this very important comment.
 */
class Foo {
private:

   /**
    * A big long comment that describes the variable. Just because the variable is
    * private doesn't mean you don't have to describe it. You might have getters and
    * setters for the variable, for example.
    */
   SomeType some_name;

public:
   ...

   // Getters and setters
   ...

   // Getter for some_name. Note that there is no setter.
   SomeType get_some_name () const { return some_name; }

   ...

};

In Version A habe ich alles dokumentiert - außer der Klasse selbst. Eine Klasse ist im Allgemeinen nicht selbstdokumentierend. Die Kommentare in Version A sind absolut nutzlos oder sogar schlimmer als nutzlos. Das ist das Hauptproblem bei der Einstellung "Alles kommentieren". Dieser kleine knappe Kommentar zum privaten Datenelement kommuniziert nichts, und die Sauerstoffkommentare zum Getter haben einen negativen Wert. Der Getter get_some_name()braucht eigentlich keinen Kommentar. Was es tut und was es zurückgibt, ist aus dem Code offensichtlich ersichtlich. Dass es keinen Setter gibt - darauf muss man schließen, weil er nicht da ist.

In Version B habe ich dokumentiert, was kommentiert werden muss. Der Getter hat keinen Sauerstoffkommentar, aber einen Kommentar, der besagt, dass es keinen Setter gibt.

Stellen Sie sicher, dass Ihre Kommentare zählen, und achten Sie darauf, dass Kommentare häufig nicht beibehalten werden, um Änderungen am Code widerzuspiegeln.