Jak mam przygotować mój kod na OpenSourcing i umieścić go w GitHub?

Za kilka tygodni mój projekt będzie gotowy i chcę zacząć przygotowywać mój kod, aby inni mogli go używać.

Zamierzam publikować wszystko na GitHub, aby ludzie mogli je ulepszyć i, mam nadzieję, poprawić.

Myślę, że pytam, jaki byłby najlepszy sposób, aby upewnić się, że mój kod jest wystarczająco udokumentowany i sformułowany w sposób odpowiedni dla innych osób?

Wiem, że zawsze powinieneś komentować wszystko i zamierzam wprowadzić funkcję @params dla każdej metody, ale czy są jeszcze jakieś inne wskazówki?

• Upewnij się, że w katalogu głównym repozytorium znajduje się plik README.txt, który wskazuje ludziom instrukcje, jak go zbudować. Instrukcje mogą znajdować się w tym pliku lub w osobnym pliku lub na stronie wiki.
• Najlepiej jest zrobić to, abyś mógł całkowicie zbudować i przetestować kod za pomocą jednego polecenia. Nie wymagaj wielu ręcznych kroków.
• Upewnij się, że masz testy dla kodu. Zapewnia to dogodne miejsce dla innych programistów, aby zobaczyć, jak używany jest kod, a także zapewnia siatkę bezpieczeństwa dla osób, które modyfikują kod. Wiedza, że ​​mogę edytować kod, a następnie uruchomić pakiet, aby sprawdzić, czy coś złamałem, jest nieoceniona.
• Postępuj zgodnie ze standardowymi standardami kodowania lub opublikuj te, których używasz.
• Jeśli twój kod używa OO, upewnij się, że przynajmniej wszystkie publiczne metody i atrybuty mają wystarczającą dokumentację
• Upewnij się, że jest jasne, jakiej licencji używa Twój kod. Zazwyczaj oznacza to dołączenie pliku LICENSE.txt lub zastosowanie dowolnego mechanizmu wymaganego przez konkretną licencję. Dokonaj świadomego wyboru licencji. Nie używaj tylko GPL, bo to wszystko, co wiesz. Podobnie, nie używaj tylko BSD, MIT lub Apache, jeśli to wszystko, co znasz ... poświęć godzinę na ich badanie, aby przynajmniej zrozumieć podstawową różnicę między licencjami GPL i nie-GPL.
• Usuń wszystkie poufne informacje z kodu, takie jak zakodowane nazwy użytkownika, hasła, adresy e-mail, adresy IP, klucze API itp. (Dzięki Hakan Deryal za sugestię)

Dokumentacja w pliku źródłowym jest zawsze dobra, ale należy opublikować dodatkową dokumentację na stronie internetowej. Wyjaśnij cel, jak to działa, twoje plany na przyszłość, postaraj się ułatwić wkład (w przeciwnym razie ... nikt ci nie pomoże) i umieść tutoriale.

Próba pracy nad projektem z samą dokumentacją kodu źródłowego zawsze jest frustrująca.

Myślę, że pytam, jaki byłby najlepszy sposób, aby upewnić się, że mój kod jest wystarczająco udokumentowany i sformułowany w sposób odpowiedni dla innych osób?

Jako otwarte oprogramowanie najważniejsze są komentarze dotyczące praw autorskich i umów licencyjnych. Zamiast długiego komentarza na początku każdego pliku, możesz użyć krótkiego i słodkiego komentarza, który krótko określa prawa autorskie i odsyła czytelnika do license.txt w katalogu głównym.

Wiem, że zawsze powinieneś komentować wszystko i zamierzam wprowadzić funkcję @params dla każdej metody, ale czy są jeszcze jakieś inne wskazówki?

Skomentować wszystko? Nie. Skomentuj ten kod, który naprawdę wymaga komentarza. Komentuj oszczędnie. Jako potencjalny użytkownik fragmentu kodu, którą z dwóch poniższych wersji definicji klasy wolisz zobaczyć?

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

   ...
};

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

   ...

};

W wersji A wszystko udokumentowałem - z wyjątkiem samej klasy. Klasa ogólnie nie jest samokontraktowana. Komentarze obecne w wersji A są absolutnie bezużyteczne, a nawet gorsze niż bezużyteczne. To jest kluczowy problem z podejściem „komentuj wszystko”. Ten krótki zwięzły komentarz do prywatnego członka danych niczego nie komunikuje, a komentarze doxygen na temat gettera mają wartość ujemną. Getter get_some_name()tak naprawdę nie potrzebuje komentarza. To, co robi i co zwraca, jest oczywiste z kodu. Że nie ma setera - musisz to wywnioskować, ponieważ go nie ma.

W wersji B udokumentowałem to, co wymaga komentarza. Getter nie ma komentarza doxygen, ale ma komentarz mówiący, że nie ma setera.

Licz swoje komentarze i uważaj, że komentarze często nie są utrzymywane, aby odzwierciedlić zmiany w kodzie.