Si consiglia di usare DocBlock anche se non sto usando phpDocumentor?

Question

Si consiglia di usare DocBlock anche se non sto usando phpDocumentor?

#1 da (4 voti)
#2 da (2 voti)

4

Sto sviluppando un sito Web semplice per un cliente.

Ho letto di phpDocumentor e DocBlocks e ho pensato che la documentazione delle mie lezioni e funzioni sarebbe molto utile.

Sono quasi sicuro che non non genererà alcuna documentazione per il sito, dal momento che è un sito web piuttosto semplice e indovina cosa? Non ha un'API ...

Ma è ancora consigliabile scrivere DocBlocks nel mio codice? Da quello che so molti programmatori non scrivono nemmeno commenti semplici, ma DocBlocks.
Non ho intenzione di generare alcuna documentazione leggibile dal client / programmatore successivo, ma continuo a pensare che fare alcuni commenti che vanno ben oltre il semplice testo sarà migliore.

edit - Se pensate che DocBlocks sia ridondante nel mio caso, ci sono altri "standard" per scrivere commenti / documentazione?
L'ultima volta che tutto ciò che non ha uno standard mi fa sentire stupido, non sono sicuro che sia meglio scrivere if(){ o if () { , /* */ o // , ecc.

Sono nuovo per il documentor e DockBlocks, e non sono ancora sicuro se devo scrivere questa domanda qui o in StackOverflow. Grazie mille comunque

php documentation

posta Nadav S. 12.07.2012 - 22:48

fonte

2 risposte

Leggi altre domande sui tag php documentation

Prezzi software personalizzato? [chiuso] Implementazione più efficiente di un albero in C ++

score 4 · Answer 1

È utile documentare cose simili in modo simile. Questo facilita la lettura del codice in quanto puoi cogliere facilmente le cose importanti. Utilizzare uno standard stabilito come base è utile in quanto i nuovi membri del team si abitueranno rapidamente allo schema. il formato phpdocumentor è basato su JavaDoc. La stessa forma è talvolta usata anche in altre lingue. Pertanto anche gli sviluppatori che non hanno familiarità con PHP sono più inclini a capire e ad usarlo rapidamente.

Strumenti aggiuntivi come IDE supportano il formato. E può ricavare informazioni per un certo aiuto da esso.

Se devi essere severo nell'usarlo è una domanda diversa. Potresti usare solo piccole parti di esso e modificare gli altri in base alle tue esigenze. Proprio come con qualsiasi altro strumento; -)

score 2 · Answer 2

Ai miei precedenti lavori non abbiamo usato DocBlocks per PHP se il codice non era un'API e non sarebbe stato utilizzato per generare documentazione. Ecco la nostra filosofia sui commenti:

Utilizza /**/ solo per la documentazione formale nella parte superiore dello script che include autore, data, breve descrizione, ecc. Usa // per tutti gli altri commenti.

Abbiamo notato che i commenti possono essere superati e trasformarsi in bugie sul codice. Invece, cercheremmo di scrivere un codice "auto-illuminante" scegliendo nomi di funzioni / classi che riflettano meglio il loro scopo / funzione. Vorremmo anche ridimensionare le funzioni complesse in funzioni più semplici che "fanno una cosa" invece di scrivere funzioni di grandi dimensioni con un breve commento del romanzo sopra di esso per cercare di descrivere cosa ha fatto.

L'unico vantaggio che posso vedere è che mancano etichettare gli argomenti della funzione su quale tipo di dati si aspettano e quale tipo di dati è il valore restituito. Ma di nuovo, PHP è un linguaggio vagamente dattiloscritto in cui DocBlocks potrebbe tradirti (meglio usare solo === e! == ed è _ * () funziona se hai davvero bisogno di guardare i tipi di dati).