Descrizione del flusso del programma JS in @fileoverview

Naviga le tue risposte
2

Devo modificare il codice JavaScript di altre persone. Il codice in genere carica alcuni dati da un'API Web, genera una tabella, la inserisce nella pagina HTML e allega alcuni gestori di eventi.

A causa della natura asincrona, il flusso del programma è piuttosto confuso, quindi sto cercando di documentarlo brevemente, altrimenti ogni volta che mi perdo cerco di capire quale parte del codice devo modificare. Ad esempio, se devo modificare alcuni valori dopo che i dati sono stati caricati da un'API Web, ma prima che venga inserito nella tabella, devo capire dove si verifica il caricamento dei dati e dove avviene il rendering HTML.

Ecco come lo sto facendo: 

/**
 * @fileOverview Custom code for the Candidates List page.
 * Program flow on page load:
 * - customSearchInit()
 *   - initSearchPage()
 *     - populateDropdownFields()
 *     - LoadAdditionalListDataAndContinue()
 *       - loadListData()
 *         - generateHtmlTable()
 *         - finishAsync()
 *           - completePageLoad()
 */

Esiste una sintassi raccomandata / popolare per documentare il flusso del programma? È una pratica comune farlo?

    
posta K48 02.08.2017 - 06:20
fonte

1 risposta

1

Il modo comune per illustrare il comportamento in un modo consumabile dall'uomo è con un diagramma di sequenza . Mostra la collaborazione tra i componenti del sistema e può gestire complessità come la concorrenza e i messaggi asincroni.

Penso che la tua sintassi nel codice sarà difficile per chiunque ma tu capirai, e invece creerei un diagramma di sequenza che vive nella documentazione del progetto, e puoi usare un JSDoc (presumo dal tag @fileOverview che stai usando JSDoc) per fare riferimento al diagramma della sequenza. 

/**
 * @fileOverview Custom code for the Candidates List page.
 * See [this diagram](../docs/candidates-sequence.png) to understand the behavior of the page load
 */

Preferisco utilizzare lo strumento di descrizione del diagramma di sequenza basato su testo PlantUML per creare i miei diagrammi di sequenza. È open source e poiché è basato su testo rende facile il controllo della versione. Se lo volessi davvero, potresti anche inserire il codice di Plantum direttamente nella documentazione del tuo file avvolgendo con <pre><code> tag.

Fai attenzione che la documentazione come questa spesso si discosta dall'attuale implementazione mentre le modifiche di implementazione.

    
risposta data 02.08.2017 - 06:36
fonte

Leggi altre domande sui tag

Progettazione di un'applicazione a singola pagina multi-tenant per il web comunicare i micro-servizi in un linguaggio statico (java)