Come si dovrebbe commentare e concedere in licenza un insieme di file di codice prima di caricarlo al pubblico? [duplicare]

4

Ho scritto un buon pezzo di codice negli ultimi giorni e sono pronto per git init e lo spingo su github. Ma prima di farlo, voglio farlo nel modo "corretto" nel caso in cui qualcun altro voglia usare il mio codice. Quindi suppongo di dover scegliere una licenza (probabilmente il MIT) e implementarla, e scrivere una sorta di commento nella parte superiore di ogni file.

Che cosa è un buon commento di stile da mettere all'inizio del file? Quali informazioni dovrebbe includere, come dovrebbe essere? E inserisco la licenza in una cartella LICENSE nella directory root o nella parte superiore di ogni file sorgente o qualcosa del genere? E ci sono altri passaggi che mi mancano prima di lanciarlo su Github?

    
posta Ricket 19.06.2011 - 20:24
fonte

3 risposte

3

Il disclaimer a due righe dovrebbe essere sufficiente, ad esempio

// (c) 2011 Ricket
// This code is licensed under MIT license (see LICENSE.txt for details)

Non dimenticare che non c'è molto senso nel codice di pubblicazione se le persone non riescono a trovarlo, quindi scrivi una buona descrizione e leggi (chissà quando qualcuno avrebbe bisogno del tuo codice anche se nessuno entra nella pagina del progetto).

    
risposta data 20.06.2011 - 00:30
fonte
1

La dichiarazione di non responsabilità:

Copyright (C) [year] by [copyright holders]

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without l> imitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Nella parte superiore di tutti i file sorgente e un file LICENSE separato nella root del progetto. Sembra ridondante, ma ogni passo per rendere chiaro il codice di licenza è un buon passo, almeno per me.

Ricorda se / quando accetti i contributi del codice per tenere traccia di chi ha inviato cosa. Se un giorno desideri cambiare la licenza, avrai bisogno di accordi con i contributori o di riscrivere il codice a meno che tu non richieda l'attribuzione del copyright (potrebbe non essere fattibile per progetti più piccoli).

    
risposta data 19.06.2011 - 20:31
fonte
0

Le altre risposte sono gli standard legali di disclaimer open source che vedi ovunque.

Ne hai bisogno.

Ma non è tutto. Fare solo le cose legali è ciò che mi fa impazzire con così tanto sviluppo open source.

Inserisci anche nella HEADER IN ALTO DEL FILE una descrizione: - Che cosa è questa (un nome breve) - Il suo scopo (una lunga descrizione, i come e perché del perché questa cosa esiste, fai finta di spiegare ai bambini di 6 anni.)

Senza queste 2 cose chiunque la guarda deve leggere la tua mente per capire che cos'è questa roba, e se è interessata a questo.

SUCCESSIVO, chiedi dei commenti.

In realtà dovresti commentare come lo hai scritto, non post-ripararlo dopo l'evento.

Tuttavia, i commenti a livello micro servono solo a sprecare tempo e ad infuriare.

fred = fred + 1;    // increment fred

Quindi, non farlo.

Metti invece un commento della sostanza prima di un pezzo di codice (non al suo interno!), definendo quale sarà la prossima cosa, essendo generale o specifico come devi essere:

//
// This implements the fast integer line drawing algorithm originally by
// Fred Nurke (see http://www.nurkesoft.com/fild), with the following
// modifications for speed:
//  - Frangle the nurgulator before decrementing the frobber;
//  - Update the decrementer pointer once only.
//
// Having done that, dispatch it to the ice-age thread where it can sit and
// grow moss for a couple of decades.
//
<neat code comes here for perhaps 10 - 20 lines>

Come generalizzazione ROUGH, un grumo di codice in esecuzione per più di circa 20-30 linee sta diventando un po 'troppo grande - quindi questa è la dimensione approssimativa per un chunk che ha bisogno di un commento esplicativo. Quasi tutto il codice avrà blocchi che sono circa 5 - 30 linee in un blocco con un commento adatto per quel blocco. (Quel blocco svolge qualche funzione o ha qualche scopo che puoi descrivere.)

E infine, i commenti dovrebbero essere ben disposti, non dovrebbero usare acronimi eccessivi o oscuri, dovrebbero leggere come inglese normale, dovrebbero essere grammaticalmente corretti e opportunamente punteggiati.

    
risposta data 20.06.2011 - 09:44
fonte

Leggi altre domande sui tag