¿Cómo debo preparar mi código para OpenSourcing y ponerlo en GitHub?

En unas pocas semanas, mi proyecto estará terminado y quiero comenzar a preparar mi código para que otras personas lo usen.

Voy a publicar todo en GitHub para que la gente pueda modificarlo y, con suerte, mejorarlo.

Supongo que lo que pregunto es, ¿cuál sería la mejor manera de asegurarme de que mi código esté suficientemente documentado y redactado correctamente para que otras personas lo usen?

Sé que siempre debes comentar todo y voy a poner la función @params para cada método, pero ¿hay otros consejos en general?

• Asegúrese de que haya un archivo README.txt en la raíz del repositorio que señale a las personas las instrucciones sobre cómo construirlo. Las instrucciones podrían estar en ese archivo, o podrían estar en un archivo separado o página wiki.
• Idealmente, hágalo para que pueda construir y probar completamente el código con un solo comando. No requiera muchos pasos manuales.
• Asegúrese de tener pruebas para el código. Esto proporciona un lugar conveniente para que otros desarrolladores vean cómo se usa su código, además proporciona una red de seguridad para las personas que modifican su código. Saber que puedo editar su código y luego ejecutar una suite para ver si he roto algo es invaluable.
• Siga los estándares de codificación comunes o publique los que usa.
• Si su código usa OO, asegúrese de que al menos todos los métodos y atributos públicos tengan suficiente documentación
• Asegúrese de que esté claro qué licencia usa su código. Por lo general, esto significa incluir un archivo LICENSE.txt, o seguir cualquier mecanismo que requiera su licencia específica. Además, tome una decisión consciente sobre la licencia. No solo use GPL porque eso es todo lo que sabe. Del mismo modo, no solo use BSD o MIT o Apache si eso es todo con lo que está familiarizado ... dedique una hora a investigarlos para que al menos comprenda la diferencia fundamental entre las licencias GPL y no GPL.
• Elimine toda la información confidencial del código, como nombres de usuario codificados, contraseñas, direcciones de correo electrónico, direcciones IP, claves API, etc. (gracias a Hakan Deryal por la sugerencia)

La documentación en el archivo fuente siempre es buena, pero debe publicar documentación adicional en un sitio web. Explica su objetivo, cómo funciona, tus planes futuros, intenta hacer una contribución fácil (de lo contrario ... nadie te ayudará) y pon algunos tutoriales.

Intentar trabajar en un proyecto solo con documentación del código fuente siempre es frustrante.

Supongo que lo que pregunto es, ¿cuál sería la mejor manera de asegurarme de que mi código esté suficientemente documentado y redactado correctamente para que otras personas lo usen?

Como código abierto, los comentarios más importantes de todos son los comentarios sobre derechos de autor y acuerdos de licencia. En lugar de un gran comentario largo al comienzo de cada archivo, es posible que desee utilizar uno breve y dulce que especifique brevemente los derechos de autor y remita al lector a license.txt en el directorio raíz.

Sé que siempre debes comentar todo y voy a poner la función @params para cada método, pero ¿hay otros consejos en general?

Comenta todo? No. Comenta ese código que realmente necesita comentarios. Comenta con moderación. Como usuario potencial de un fragmento de código, ¿cuál de las siguientes dos versiones de una definición de clase preferiría ver?

Versión 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; }

   ...
};

Versión 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; }

   ...

};

En la versión A, he documentado todo, excepto la clase misma. Una clase en general no es autodocumentada. Los comentarios que están presentes en la versión A son absolutamente inútiles, o incluso peores que inútiles. Ese es el problema clave con la actitud de "comentar todo". Ese pequeño comentario breve sobre el miembro de datos privados no comunica nada, y los comentarios de doxygen sobre el captador tienen un valor negativo. El captador get_some_name()realmente no necesita un comentario. Lo que hace y lo que devuelve es evidentemente obvio en el código. Que no hay setter, tienes que inferir eso porque no está allí.

En la versión B, he documentado lo que necesita comentarios. El getter no tiene un comentario de doxygen, pero tiene un comentario que menciona que no hay setter.

Haga que sus comentarios cuenten y tenga en cuenta que los comentarios a menudo no se mantienen para reflejar los cambios en el código.