Как мне подготовить код для OpenSourcing и поместить его на GitHub?

Через несколько недель мой проект будет завершен, и я хочу начать готовить свой код, чтобы его могли использовать другие люди.

Я собираюсь публиковать все на GitHub, чтобы люди могли настроить его и, надеюсь, сделать его лучше.

Я думаю, что я спрашиваю, что было бы лучшим способом убедиться, что мой код достаточно документирован и сформулирован правильно для использования другими людьми?

Я знаю, что вы всегда должны комментировать все, и я собираюсь добавить функцию @params для каждого метода, но есть ли какие-либо другие советы в целом?

• Убедитесь, что в корне репозитория есть файл README.txt, который указывает людям на инструкции по его сборке. Инструкции могут быть в этом файле или в отдельном файле или на вики-странице.
• В идеале, сделайте так, чтобы вы могли полностью собрать и протестировать код с помощью одной команды. Не требует кучу ручных шагов.
• Убедитесь, что у вас есть тесты для кода. Это обеспечивает удобное место для других разработчиков, чтобы увидеть, как используется ваш код, плюс это обеспечивает безопасность для людей, которые изменяют ваш код. Знание, что я могу отредактировать ваш код и затем запустить пакет, чтобы увидеть, не сломал ли я что-либо, неоценимо.
• Следуйте общим стандартам кодирования или опубликуйте те, которые вы используете.
• Если ваш код использует OO, убедитесь, что по крайней мере все публичные методы и атрибуты имеют достаточную документацию
• Убедитесь, что понятно, какую лицензию использует ваш код. Как правило, это означает включение файла LICENSE.txt или использование любого механизма, который требуется для вашей конкретной лицензии. Также сделайте осознанный выбор по поводу лицензии. Не просто используйте GPL, потому что это все, что вы знаете. Аналогично, не просто используйте BSD, MIT или Apache, если это все, с чем вы знакомы ... потратьте час на их изучение, чтобы хотя бы понять принципиальную разницу между лицензиями GPL и не-GPL.
• Удалите всю конфиденциальную информацию из кода, такую ​​как жестко запрограммированные имена пользователей, пароли, адреса электронной почты, IP-адреса, ключи API и т. Д. (Спасибо Hakan Deryal за предложение)

Документация в исходном файле всегда хороша, но вы должны опубликовать дополнительную документацию на веб-сайте. Объясните его цель, как это работает, ваши планы на будущее, постарайтесь сделать вклад легко (иначе ... никто не поможет вам) и поместите несколько учебных пособий.

Попытка работать над проектом только с документацией по исходному коду всегда разочаровывает.

Я думаю, что я спрашиваю, что было бы лучшим способом убедиться, что мой код достаточно документирован и сформулирован правильно для использования другими людьми?

Что касается открытого исходного кода, наиболее важными комментариями являются комментарии об авторском праве и лицензионном соглашении. Вместо большого длинного комментария в начале каждого файла вы можете использовать короткий и приятный комментарий, который кратко определяет авторские права и направляет читателя в файл license.txt в корневом каталоге.

Я знаю, что вы всегда должны комментировать все, и я собираюсь добавить функцию @params для каждого метода, но есть ли какие-либо другие советы в целом?

Комментировать все? Нет. Комментируйте тот код, который действительно нуждается в комментариях. Комментарий экономно. Как потенциальный пользователь куска кода, какую из следующих двух версий определения класса вы бы предпочли увидеть?

Версия А:

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

   ...
};

Версия Б:

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

   ...

};

В версии A я задокументировал все - кроме самого класса. Класс вообще не самодокументируется. Комментарии, которые присутствуют в версии A, абсолютно бесполезны или даже хуже, чем бесполезны. Это ключевая проблема с отношением «комментировать все». Этот небольшой краткий комментарий о члене с закрытыми данными ничего не сообщает, а комментарии о кислороде для получателя имеют отрицательное значение. Получатель get_some_name()не нуждается в комментариях. Что он делает и что возвращает, очевидно из кода. Что нет сеттера - вы должны сделать вывод, что его там нет.

В версии B я задокументировал то, что требует комментариев. Получатель не имеет комментария doxygen, но в нем есть комментарий, в котором говорится, что нет установщика.

Сделайте так, чтобы ваши комментарии учитывались, и помните, что комментарии часто не поддерживаются, чтобы отразить изменения в коде.