Como devo preparar meu código para o OpenSourcing e colocá-lo no GitHub?

Dentro de algumas semanas, meu projeto estará concluído e quero começar a preparar meu código para que outras pessoas o usem.

Vou postar tudo no GitHub para que as pessoas possam ajustá-lo e, com sorte, melhorar.

Acho que o que estou perguntando é: qual seria a melhor maneira de garantir que meu código esteja suficientemente documentado e redigido corretamente para que outras pessoas o usem?

Eu sei que você sempre deve comentar tudo e eu vou colocar o recurso @params para todos os métodos, mas existem outras dicas em geral?

• Certifique-se de que exista um arquivo README.txt na raiz do repositório que indique as pessoas para instruções sobre como construí-lo. As instruções podem estar nesse arquivo ou em um arquivo ou página wiki separada.
• Idealmente, faça com que você possa construir e testar completamente o código com um único comando. Não exija várias etapas manuais.
• Verifique se você tem testes para o código. Isso fornece um local conveniente para outros desenvolvedores verem como seu código é usado, além de fornecer uma rede de segurança para as pessoas que modificam seu código. Saber que posso editar seu código e, em seguida, executar um conjunto para ver se quebrei algo é inestimável.
• Siga os padrões comuns de codificação ou publique os que você usa.
• Se seu código usar OO, verifique se pelo menos todos os métodos e atributos públicos possuem documentação suficiente
• Verifique se está claro qual licença seu código usa. Normalmente, isso significa incluir um arquivo LICENSE.txt ou seguir qualquer mecanismo que sua licença específica exija. Além disso, faça uma escolha consciente sobre a licença. Não use apenas a GPL, porque é tudo o que você sabe. Da mesma forma, não use o BSD, o MIT ou o Apache, se você conhece tudo isso ... gaste uma hora pesquisando essas informações para entender pelo menos a diferença fundamental entre as licenças GPL e não GPL.
• Remova todas as informações confidenciais do código, como nomes de usuário codificados, senhas, endereços de email, endereços IP, chaves de API etc. (obrigado por Hakan Deryal pela sugestão)

A documentação no arquivo de origem é sempre boa, mas você deve publicar documentação adicional em um site. Explique seu objetivo, como funciona, seus planos futuros, tente facilitar a contribuição (caso contrário ... ninguém o ajudará) e faça alguns tutoriais.

Tentar trabalhar em um projeto apenas com documentação de código-fonte é sempre frustrante.

Acho que o que estou perguntando é: qual seria a melhor maneira de garantir que meu código esteja suficientemente documentado e redigido corretamente para que outras pessoas o usem?

Como código aberto, os comentários mais importantes de todos são os comentários sobre direitos autorais e contrato de licença. Em vez de um grande e longo comentário no início de cada arquivo, convém usar um pequeno e doce que especifique brevemente os direitos autorais e encaminhe o leitor para license.txt no diretório raiz.

Eu sei que você sempre deve comentar tudo e eu vou colocar o recurso @params para todos os métodos, mas existem outras dicas em geral?

Comentar tudo? Não. Comente o código que realmente precisa de comentários. Comente com moderação. Como usuário potencial de um pedaço de código, qual das duas versões a seguir de uma definição de classe você prefere ver?

Versão 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; }

   ...
};

Versão 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; }

   ...

};

Na versão A, eu documentei tudo - exceto a própria classe. Uma classe em geral não é auto-documentada. Os comentários presentes na versão A são absolutamente inúteis ou até piores que inúteis. Esse é o principal problema com a atitude "comentar tudo". Esse pequeno comentário conciso sobre o membro de dados particulares não comunica nada e os comentários do doxygen no getter têm valor negativo. O getter get_some_name()realmente não precisa de um comentário. O que ele faz e o que retorna é obviamente óbvio no código. Que não existe criador - você deve inferir isso porque não existe.

Na versão B, eu documentei o que precisa ser comentado. O getter não tem um comentário doxygen, mas tem um comentário mencionando que não há nenhum setter.

Faça com que seus comentários sejam importantes e lembre-se de que os comentários muitas vezes não são mantidos para refletir as alterações no código.