Come commentare il file system?

Question

Come commentare il file system?

#1 da (5 voti)
#2 da (3 voti)
#3 da (1 voti)

3

Quando alcune parti del codice sono insolite o poco chiare, la pratica comune è di lasciare un commento che spieghi perché è così. Tuttavia, a volte un filesystem può avere configurazioni insolite, come una directory con privilegi di 0477. C'è qualche convenzione per lasciare commenti su questo?

Sto scrivendo un 'Developers Wiki' per l'azienda in quanto sarebbe il posto giusto per queste cose. Tuttavia preferirei qualcosa di più standard se esiste e più accessibile quando, ad esempio, i ragazzi successivi devono accedere a SSH da casa nel cuore della notte e potrebbe non pensare di controllare il wiki ( o persino avere accesso ad esso).

standards

posta dotancohen 18.06.2014 - 16:59

fonte

3 risposte

3

In un progetto, è tipico avere un readme o un sommario del progetto, e in esso è garantita una rapida descrizione della struttura del progetto. Ecco, penso che potresti inserire una spiegazione per i permessi delle directory. Se lo sviluppatore non dovesse riuscire a controllare il wiki, si spera che pensino di controllare il readme.

Questo risponde alla tua domanda?

risposta data 18.06.2014 - 17:03

fonte

1

Per aggiungere alla risposta di @ Neil sopra, sarebbe anche molto utile inserire un file readme nella directory in questione. Dopo 6 mesi (o 6 anni) dal termine del progetto, gli sviluppatori potrebbero non sapere nemmeno quale progetto ha causato il cambiamento, per trovare il wiki / readme. Simile ai commenti nel codice, questo mette la spiegazione giusta con il problema / outlier.

Questa soluzione può anche aiutare i tuoi amministratori di sistema a eseguire il debug e correggere il problema senza doverti chiamare. Queste persone non avranno idea di quale progetto sia coinvolto, ma avranno le informazioni proprio di fronte a loro.

risposta data 18.06.2014 - 17:16

fonte

Leggi altre domande sui tag standards

Perché un oggetto "Ordine" dovrebbe avere una proprietà "Stato"? Perché non monad prendere '(M a - M b)'?

score 5 · Accepted Answer

Qualsiasi luogo in cui il tuo codice prevede una configurazione insolita, verifica esplicitamente tale configurazione e spiega chiaramente l'aspettativa nella corrispondente voce del messaggio di errore / voce del file di registro.

Se Ops chiama il tuo ragazzo alle 2 del mattino con

"TheApp si è schiantato con un messaggio 'errore 2468: / rootdir / specialdir deve avere i privilegi di 0477'", quindi almeno la sua correzione SSH sarà veloce.

Nota a margine, se possibile , cerca di evitare questa situazione. Le configurazioni standard / vanilla sono più facili da mantenere / più difficili da rovinare.

Chiarimento: oltre a qualsiasi documentazione, assicurati anche che il codice "documenti" il problema con controlli espliciti e gestione degli errori. La prima cosa che una persona legge quando c'è un problema non è il doc o il wiki, è il messaggio di errore.