StormForge Labs (C05)
Presentazione: 27
Giudizio complessivo sui documenti: 23
Considerazioni generali
Oltre a identificare l'autore, il verificatore, il responsabile dell'accettazione, il registro delle modifiche deve anche, per ogni versione, fornire informazione sufficiente per identificare ogni modifica apportata e specificarne la ragione.
Tra i riferimenti normativi manca il documento di Norma di Progetto. Tra i riferimenti informativi manca il documento di AR.
Il glossario deve avere versione ed essere riferito con essa. Un riferimento indistinto all’intera Wikipedia non ha alcun significato.
Nonostante la raccomandazione precedentemente non avete corretto l'errore strutturale nel controllo del numero totale di pagine da inserire nel piè di pagina dei documenti.
Norme di Progetto (v3.0)
Manca l'indice. Le regole di versionamento attuali suggeriscono che dalle versione X.Y si possa transitare direttamente alla [X+1].Y, il che non ha senso perché “consuma” inutilmente Y indici nella storia di [X+1]. Per il resto il contenuto del documento è discreto.
Specifica Tecnica (v1.0)
Errore già nel sommario: “i prof. Vardanega”. Sez. 1.1: come si può fornire una descrizione generale dell’architettura, dovendo scendere a livello di dettaglio? Il riferimento al glossario non porta alcuna versione. Sez. 2.1: che versione di UML si utilizza? Se le gerarchie di classi individuate nel documento non sono significative perché il linguaggio usato è JS, allora occorre trovare un altro sistema di progettazione. Nel descrivere i design pattern utilizzati è necessario anche contestualizzarli nel progetto. Converrà dunque spostare la descrizione dei pattern più avanti nel documento. Sez. 2.2.1: il pattern non “indica” un oggetto, ma viene “realizzato da” esso. Bene il pattern Composite. Bene la descrizione dei pattern, che però non è altro che la traduzione delle descrizioni fornite dagli autori GoF originali. Pag. 11: la figura 7 non è un “grafico”, ma un diagramma delle classi. Fig. 8: un package non può estendere una classe. Il membro di classe “content” è contenuto in tutte le sottoclassi di BaseShape: perché non portarlo in BaseShape con identificatore protetto? Le classi hanno quasi tutti i membri di classe pubblici: siete sicuro che sia una scelta opportuna rispetto, per esempio a sani principi di information hiding? Quali sono i metodi astratti di BaseShape che rendono astratta tale classe? Pag. 12: il package individuato nel diagramma è “Layout” e non “layout”. In fig. 9 lo stesso package diventa “Layouts”. Perché initGui, pur essendo una classe, ha la prima lettera del nome minuscola? La dissertazione sull’esempio di interfaccia grafica va spostata in appendice. Perché in fig. 11 i membri di classe sono ora identificati con lettere maiuscole? Sono forse costanti? La relazione fra la classe Controller e il package sys.GUI.Widget è errata, in quanto Controller possiede diversi membri di classe di tipo BaseShape. Anche la relazione con la classe CSS è errata, così come la relazione con il package Pages. Non pare corretto demandare al package Data (ossia il package di gestione dei dati) la comunicazione fra client e server. In una architettura three tier questa dovrebbe essere inserita nel package Core. Pag. 17: non è la “sezione” Parser, ma il package. Fig. 14: BaseElement dovrebbe essere astratta. Sez. 3.1: modulo à package. Nella descrizione delle componenti, ossia i paragrafi 3.x, oltre alla descrizione della classe, che ha un buon grado di dettaglio per il documento di ST, è necessario inserire anche le relazioni da e verso le altre componenti. Fra l’altro, le componenti descritte sono in numero molto maggiore rispetto a quelle riportate nei diagrammi: in linea di principio il documento di ST deve descrivere solo le componenti principali. Perché il nome delle classi del modulo Data non iniziano con la lettere maiuscola? Dove sono finite le classi Client e Server? Come avviene la comunicazione? Pag. 26: “cos”. La descrizione del diagramma in figura 15 parla di tutto fuorché di quel che è descritto dal diagramma! Fig. 16: molto brutto spezzare un diagramma di sequenza su due pagine. Sembra che nella generazione del PDF siano saltate tutte le lettere accentate: correggere. Descrizione del diagramma in fig. 16 troppo insufficiente rispetto al contenuto di informazione. Pag. 32: caratteri strani intorno alla parola canvas.
In definitiva, il documento descrive in modo insufficiente le componenti dell’architettura logica, e lo fa spesso senza seguire un filo logico progettuale (p.es. decomposizione top­down). I pattern adottati non sono contestualizzati e la trattazione di una parte importante della comunicazione client­server è te tutto omessa. Attenzione a dotarvi di disciplina nell’utilizzo del linguaggio JS per ottenere codice di qualità accettabile. Bene il tracciamento.
Definizione di Prodotto (v1.0)
Due errori già nel sommario (tra cui “i prof. Vardanega”). Lo scopo del documento di DP non è quello di illustrare l’architettura logica, ma quello di descrivere le componenti (che non si chiamano “parti del sistema”) dell’architettura di dettaglio. Tra i riferimenti informativi manca il documento di ST. Il capitolo 2 appartiene alle norme di progetto: spostare. Prima di iniziare la descrizione delle componenti di dettaglio, sarebbe opportuno riportare un diagramma dei package o un diagramma delle classi ad alto livello che possa introdurre l’architettura delle componenti che si andranno a descrivere. Perché la classe initGUI inizia con la lettera minuscola? Il titolo della sezione 3.1 non è il reale nome della classe. La descrizione del metodo initGUI della classe InitGUI è inappropriato: mai chiamare un metodo con il nome della classe se non è un costruttore. ListLayouts è una classe che non compare in alcun diagramma, né in ST né in DP. Inoltre la classe non ha membri di classe, non ha metodi e non è astratta e neppure interfaccia: a cosa serve? Analogamente per ListPage e ListWidgets. Pag. 10: il diagramma in figura 2 non ha senso senza una introduzione o un riferimento nelle descrizioni. Sez. 3.5: BaseShape è la classe madre, base per le sue derivate, non un modello. Quali sono i metodi che rendono astratta BaseShape? Sez. 3.6, descrizione del metodo paint(): quali sono le necessarie modifiche (analogamente per tutte le classi derivate da BaseShape)? Sez. 3.7: perché usare una stringa per il membro checkObj e non un tipo booleano? Sez. 3.11: cos’è e come viene utilizzato l’oggetto Mixed nel mtodo loadData? Notate che il membro idObj, presente in tutte le sottoclassi di BaseShape ha sempre la stessa descrizione: “identifica univocamente ogni oggetto pulsante”. Pag. 25: altro diagramma non introdotto. Sez. 3.21: perché ci sono membri di classe con nomi scritti in maiuscolo, ma che non sono costanti? Sez. 3.23: immagino che il nome della classe sia TableLayout. Sez. 4.1: quali informazioni compongono lo “stato dell’applicazione”? Tutti i membri di classe hanno ora nomi scritti con lettere maiuscole. Sez. 4.2, CSS: altra classe senza metodi. Fig. 5: altra figura posizionata senza un’introduzione. Sez. 4.10: quali sono i metodi che rendono astratta BasePage? Perché il metodo clear() ritorna un riferimento a una BasePage? Perché tutte le classi derivate da BasePage non hanno metodi? Sono forse astratte a loro volta? Improbabile. Fig. 1­5, nella didascalia: diagramma (?) del package invece che diagramma delle classi. La fig. 6 non è un diagramma di sequenza! 5.1: La classe IO nel documento di ST aveva nome Client: spiegate perché il nome sia cambiato. Come fa il client a conoscere i riferimenti al server? (Non vi è traccia di URL.) Come avviene la comunicazione con il server? Queste informazioni sono importanti, perché probabilmente questa sarà l’unica componente non scritta in JS e non è banale! Manca la descrizione di tutte le classi del package Parser. Il tracciamento è ben pensato come struttura, ma non tutte le classi sono presenti. Addirittura la tabella 1 e 2 non contengono nemmeno lo stesso insieme di classi (ad esempio, dov’è finita la classe BaseShape?). 3 dei 4 diagrammi di sequenza sono già stati riportati, identici, nel documento di ST.
Nel complesso il documento è poco organico e molto confusionario nella descrizioni delle componenti. Il grado di dettaglio non è adeguato nemmeno per un JavaDoc e alcune descrizioni sono scarsamente informative. I diagrammi presentati sono gli stessi del documenti di ST e il tracciamento è incompleto. Inserire descrizioni maggiori almeno per i metodi più complessi, portando qualche diagramma di sequenza o attività che ne descriva il flusso logico. Inserire soprattutto una descrizione di come si intende implementare la comunicazione tra client e server. Documento da rivedere.
Piano di Progetto (v3.0)
Documento di qualità apprezzabile. Apprezzabile l'informazione di raffronto tra preventivo e consuntivo. Non vi è traccia tuttavia di quali esiti tale raffronto possa o debba avere in senso correttivo o migliorativo sul preventivo a finire. Senza di ciò, il valore del consuntivo è fortemente ridotto: rivedere.
Piano di Qualifica (v3.0)
I contenuti attuali del documento lo rendono idoneo per l'inizio del progetto, ma largamente insufficiente per guidare le attività di verifica necessarie allo stato attuale. Si tratta di una lacuna grave e preoccupante.
Glossario
Documento di buona qualità. Errore nel piè di pagina, che denuncia una lacuna strutturale nel modello dei documenti.