Bagaimana saya harus menyiapkan kode saya untuk OpenSourcing dan meletakkannya di GitHub?

Dalam beberapa minggu, proyek saya akan selesai dan saya ingin mulai menyiapkan kode saya agar orang lain dapat menggunakannya.

Saya akan memposting semuanya ke GitHub sehingga orang dapat men-tweak dan semoga membuatnya lebih baik.

Saya kira apa yang saya tanyakan adalah, apa cara terbaik untuk memastikan kode saya didokumentasikan dan diucapkan dengan benar untuk digunakan orang lain?

Saya tahu Anda harus selalu mengomentari semuanya dan saya akan memasukkan fitur @params untuk setiap metode, tetapi apakah ada tips lain secara umum?

• Pastikan ada file README.txt di root repositori yang mengarahkan orang ke petunjuk tentang cara membuatnya. Instruksi bisa di file itu, atau bisa di file terpisah atau halaman wiki.
• Idealnya, buatlah sehingga Anda dapat membangun dan menguji kode sepenuhnya dengan satu perintah. Tidak memerlukan banyak langkah manual.
• Pastikan Anda memiliki tes untuk kode tersebut. Ini menyediakan tempat yang nyaman bagi pengembang lain untuk melihat bagaimana kode Anda digunakan, ditambah lagi menyediakan jaring pengaman bagi orang-orang yang memodifikasi kode Anda. Mengetahui saya dapat mengedit kode Anda dan kemudian menjalankan suite untuk melihat apakah saya memecahkan sesuatu yang tak ternilai.
• Ikuti standar pengkodean umum, atau terbitkan yang Anda gunakan.
• Jika kode Anda menggunakan OO, pastikan setidaknya semua metode dan atribut publik memiliki dokumentasi yang memadai
• Pastikan sudah jelas lisensi apa yang digunakan kode Anda. Biasanya ini berarti memasukkan file LICENSE.txt, atau mengikuti mekanisme apa pun yang diperlukan lisensi spesifik Anda. Juga, buat pilihan sadar tentang lisensi. Jangan hanya menggunakan GPL karena hanya itu yang Anda ketahui. Demikian juga, jangan hanya menggunakan BSD atau MIT atau Apache jika hanya itu yang Anda kenal ... menghabiskan satu jam meneliti mereka sehingga Anda setidaknya memahami perbedaan mendasar antara lisensi GPL dan non-GPL.
• Hapus semua informasi sensitif dari kode, seperti nama pengguna, kata sandi, alamat email, alamat ip, kunci API, dll. (Terima kasih kepada Hakan Deryal untuk sarannya)

Dokumentasi dalam file sumber selalu baik, tetapi Anda harus menerbitkan dokumentasi tambahan di situs web. Jelaskan tujuannya, cara kerjanya, rencana masa depan Anda, cobalah untuk membuat kontribusi mudah (jika tidak ... tidak ada yang akan membantu Anda) dan berikan beberapa tutorial.

Mencoba mengerjakan proyek dengan dokumentasi kode sumber saja selalu membuat frustrasi.

Saya kira apa yang saya tanyakan adalah, apa cara terbaik untuk memastikan kode saya didokumentasikan dan diucapkan dengan benar untuk digunakan orang lain?

Sebagai sumber terbuka, komentar paling penting dari semua adalah komentar hak cipta dan perjanjian lisensi. Daripada komentar panjang yang panjang di awal setiap file, Anda mungkin ingin menggunakan yang pendek dan manis yang secara singkat menentukan hak cipta dan merujuk pembaca ke license.txt di direktori root.

Saya tahu Anda harus selalu mengomentari semuanya dan saya akan memasukkan fitur @params untuk setiap metode, tetapi apakah ada tips lain secara umum?

Beri komentar semuanya? Tidak. Komentari kode yang benar-benar membutuhkan komentar. Komentar hemat. Sebagai pengguna potensial dari sejumlah kode, manakah dari dua versi definisi kelas berikut yang akan Anda lihat?

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

   ...

};

Dalam versi A saya sudah mendokumentasikan semuanya - kecuali kelas itu sendiri. Kelas secara umum tidak mendokumentasikan diri sendiri. Komentar yang ada di versi A sama sekali tidak berguna, atau bahkan lebih buruk daripada tidak berguna. Itulah masalah utama dengan sikap "komentar segalanya". Komentar singkat tentang anggota data pribadi itu tidak mengomunikasikan apa pun, dan komentar doxygen pada pengambil memiliki nilai negatif. Sang pengambil get_some_name()tidak benar-benar membutuhkan komentar. Apa yang dilakukannya dan apa yang dikembalikan jelas dari kode. Bahwa tidak ada penyetel - Anda harus menyimpulkan bahwa itu tidak ada.

Dalam versi B saya telah mendokumentasikan apa yang perlu dikomentari. Sang pengambil tidak memiliki komentar doxygen, tetapi memiliki komentar yang menyebutkan bahwa tidak ada setter.

Buat komentar Anda diperhitungkan, dan berhati-hatilah bahwa komentar seringkali tidak dikelola untuk mencerminkan perubahan pada kode.