Comment dois-je préparer mon code pour OpenSourcing et le mettre sur GitHub?

Dans quelques semaines, mon projet va être terminé et je veux commencer à préparer mon code pour que d'autres personnes puissent l'utiliser.

Je vais tout publier sur GitHub pour que les gens puissent le modifier et, espérons-le, l'améliorer.

Je suppose que ce que je demande, c'est quelle serait la meilleure façon de s'assurer que mon code est suffisamment documenté et rédigé correctement pour que d'autres personnes puissent l'utiliser?

Je sais que vous devriez toujours tout commenter et je vais mettre la fonctionnalité @params pour chaque méthode, mais y a-t-il d'autres conseils en général?

• Assurez-vous qu'il y a un fichier README.txt à la racine du référentiel qui indique aux utilisateurs des instructions sur la façon de le créer. Les instructions peuvent être dans ce fichier, ou elles peuvent être dans un fichier séparé ou une page wiki.
• Idéalement, faites en sorte que vous puissiez complètement construire et tester le code avec une seule commande. Ne nécessite pas un tas d'étapes manuelles.
• Assurez-vous d'avoir des tests pour le code. Cela permet aux autres développeurs de voir comment votre code est utilisé et offre un filet de sécurité aux personnes qui modifient votre code. Savoir que je peux éditer votre code puis lancer une suite pour voir si j'ai cassé quelque chose est inestimable.
• Suivez les normes de codage courantes ou publiez celles que vous utilisez.
• Si votre code utilise OO, assurez-vous qu'au moins toutes les méthodes et tous les attributs publics ont une documentation suffisante
• Assurez-vous que la licence utilisée par votre code est claire. Cela signifie généralement d'inclure un fichier LICENSE.txt ou de suivre le mécanisme requis par votre licence spécifique. Faites également un choix conscient au sujet de la licence. N'utilisez pas seulement la GPL car c'est tout ce que vous savez. De même, n'utilisez pas seulement BSD ou MIT ou Apache si c'est tout ce que vous connaissez ... passez une heure à les rechercher afin de comprendre au moins la différence fondamentale entre les licences GPL et non GPL.
• Supprimez toutes les informations sensibles du code, telles que les noms d'utilisateur codés en dur, les mots de passe, les adresses e-mail, les adresses IP, les clés API, etc. (merci à Hakan Deryal pour la suggestion)

La documentation dans le fichier source est toujours bonne, mais vous devez publier de la documentation supplémentaire sur un site Web. Expliquez son objectif, comment cela fonctionne, vos projets futurs, essayez de faciliter la contribution (sinon ... personne ne vous aidera) et mettez quelques tutoriels.

Essayer de travailler sur un projet uniquement avec la documentation du code source est toujours frustrant.

Je suppose que ce que je demande, c'est quelle serait la meilleure façon de s'assurer que mon code est suffisamment documenté et rédigé correctement pour que d'autres personnes puissent l'utiliser?

En tant qu'open source, les commentaires les plus importants de tous sont les commentaires sur les droits d'auteur et l'accord de licence. Plutôt qu'un long et long commentaire au début de chaque fichier, vous souhaiterez peut-être utiliser un court et doux qui spécifie brièvement les droits d'auteur et renvoie le lecteur à license.txt dans le répertoire racine.

Je sais que vous devriez toujours tout commenter et je vais mettre la fonctionnalité @params pour chaque méthode, mais y a-t-il d'autres conseils en général?

Commenter tout? Non. Commentez ce code qui a vraiment besoin de commentaires. Commentez avec parcimonie. En tant qu'utilisateur potentiel d'un morceau de code, laquelle des deux versions suivantes d'une définition de classe préféreriez-vous voir?

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; }

   ...

};

Dans la version A, j'ai tout documenté - sauf la classe elle-même. Une classe en général n'est pas auto-documentée. Les commentaires présents dans la version A sont absolument inutiles, voire pires qu'inutiles. C'est le problème clé de l'attitude "commenter tout". Ce petit commentaire laconique sur le membre de données privées ne communique rien, et les commentaires doxygen sur le getter ont une valeur négative. Le getter get_some_name()n'a pas vraiment besoin d'un commentaire. Ce qu'il fait et ce qu'il retourne est clairement évident dans le code. Qu'il n'y a pas de poseur - vous devez inférer cela parce qu'il n'est pas là.

Dans la version B, j'ai documenté ce qui doit être commenté. Le getter n'a pas de commentaire doxygen, mais il a un commentaire mentionnant qu'il n'y a pas de setter.

Faites en sorte que vos commentaires comptent et prenez garde que les commentaires ne sont souvent pas conservés pour refléter les modifications apportées au code.