Come dovrei ottenere il mio codice pronto per OpenSourcing e metterlo su GitHub?

9

Tra poche settimane, il mio progetto sarà terminato e voglio iniziare a preparare il mio codice affinché altre persone lo usino.

Ho intenzione di postare tutto su GitHub in modo che le persone possano modificarlo e, si spera, renderlo migliore.

Credo che quello che sto chiedendo sia, quale sarebbe il modo migliore per assicurarmi che il mio codice sia sufficientemente documentato e formulato per essere usato dagli altri?

So che dovresti sempre commentare tutto e inserirò la funzione @params per ogni metodo, ma ci sono altri suggerimenti in generale?

    
posta Sempus 20.09.2012 - 16:22
fonte

3 risposte

12
  • Assicurati che ci sia un file README.txt nella radice del repository che rimandi le persone alle istruzioni su come costruirlo. Le istruzioni potrebbero essere in quel file, oppure potrebbero essere in un file separato o in una pagina wiki.
  • Idealmente, fallo in modo che tu possa completamente compilare e testare il codice con un singolo comando. Non sono necessari alcuni passaggi manuali.
  • Assicurati di avere test per il codice. Ciò offre agli altri sviluppatori la possibilità di vedere come viene utilizzato il tuo codice, oltre a fornire una rete di sicurezza per le persone che modificano il tuo codice. Sapendo che posso modificare il tuo codice e quindi eseguire una suite per vedere se ho rotto qualcosa è inestimabile.
  • Segui gli standard di codifica comuni o pubblica quelli che usi.
  • Se il tuo codice utilizza OO, assicurati che almeno tutti i metodi e gli attributi pubblici abbiano una documentazione sufficiente
  • Assicurati che sia chiaro quale licenza utilizza il tuo codice. In genere ciò significa includere un file LICENSE.txt o seguire qualsiasi meccanismo richiesto dalla specifica licenza. Inoltre, fai una scelta consapevole sulla licenza. Non usare GPL solo perché è tutto ciò che sai. Allo stesso modo, non usare solo BSD o MIT o Apache se è tutto ciò che ti è familiare ... trascorri un'ora a cercare quelli, così almeno comprendi la fondamentale differenza tra licenze GPL e non GPL.
  • Rimuovi tutte le informazioni sensibili dal codice, come nomi utente codificati, password, indirizzi e-mail, indirizzi IP, chiavi API, ecc. (grazie a Hakan Deryal per il suggerimento)
risposta data 20.09.2012 - 16:31
fonte
3

La documentazione nel file sorgente è sempre buona, ma dovresti pubblicare documentazione aggiuntiva su un sito web. Spiega il suo obiettivo, come funziona, i tuoi piani futuri, cerca di rendere il contributo facile (altrimenti ... nessuno ti aiuterà) e metti alcuni tutorial.

Cercare di lavorare su un progetto con la documentazione del codice sorgente è sempre frustrante.

    
risposta data 20.09.2012 - 16:42
fonte
1

I guess what I'm asking is, what would be the best way to make sure my code is sufficiently documented and worded right for other people to use?

Come open source, i commenti più importanti di tutti sono il commento del copyright e del contratto di licenza. Piuttosto che un lungo commento all'inizio di ogni file, potresti voler usare uno short e dolce che specifica brevemente il copyright e rimanda il lettore a license.txt nella directory root.

I know you should always comment everything and I'm going to be putting in the @params feature for every method, but are there any other tips in general?

Commenta tutto? No. Commenta quel codice che ha veramente bisogno di commenti. Commento con parsimonia. Come utente potenziale di una porzione di codice, quale delle seguenti due versioni di una definizione di classe preferiresti vedere?

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

   ...
};

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

   ...

};

Nella versione A ho documentato tutto, tranne la classe stessa. Una classe in generale non è auto-documentante. I commenti che sono presenti nella versione A sono assolutamente inutili o addirittura peggiori di inutili. Questo è il problema chiave con l'atteggiamento "commenta tutto". Quel piccolo commento laconico sul membro dei dati privati non comunica nulla e i commenti doxygen sul getter hanno un valore negativo. Il getter get_some_name() non ha realmente bisogno di un commento. Quello che fa e ciò che ritorna è chiaramente ovvio dal codice. Che non ci sia un setter: devi dedurlo perché non è lì.

Nella versione B ho documentato ciò che ha bisogno di commenti. Il getter non ha un commento Doxygen, ma ha un commento che dice che non c'è setter.

Rendi contenti i tuoi commenti e fai attenzione che i commenti non vengano mantenuti per riflettere le modifiche al codice.

    
risposta data 20.09.2012 - 17:13
fonte

Leggi altre domande sui tag