Re: Luokkadokumentit

Kirjoittajan mukaan: Jukka-Pekka Santanen <jukka-pekka.santanen_at_mit.jyu.fi_at_localhost>
Päiväyksen mukaan: Fri, 25 May 2012 19:13:24 +0300
Terve!

Luokkadokumenttitiedostojen jotkut rivit ovat sen verran pitkiä ja 
kuvat isoja, että niistä kaikki eivät sopisi kokonaan tulosteeseen.
Sovin eilisen lounaan lopuksi projektiryhmän kanssa, ettei 
luokkadokumentteja tulosteta projektikansioon. Projekti-CD:lle
ne sen sijaan sijoitetaan HTML-sivuina.

> Date: Tue, 22 May 2012 11:34:08 +0300
> From: Jari Salokangas <jari.p.t.salokangas_at_student.jyu.fi>
> To: paatti_at_korppi.jyu.fi
> 
> Sovellusten päivitetyt luokkadokumentit (kuvien kanssa) löytyvät
> osoitteesta:
> http://sovellusprojektit.it.jyu.fi/paatti/luokkadokumentit/html/
> 
Kokonaisuutena luokkadokumenttien esitystapa on tiivis ja pääosin
mielestäni mallikas. Havaitsin kuitenkin luokkadokumenteissa 
useamman luokan ja metodin osalta puuttuvia tai virheellisiä 
kuvauksia. 

Luokkien kuvausten osalta tein seuraavat huomiot:
  - Luokan kuvaus uupuu luokista BelongsQueryDelegate, 
    EventsInScheduleDelegate, NewRowIDChangeEvent, 
    EventTool.NODE_MODES, NodeFactory.NODE_TYPE ja StringHelper.
  - Tekijää tai hänen yhteystietojaan ei mainita tai on muilta osin
    puutteellinen luokissa BelongsQueryDelegate, PaattiDBService,
    ContextMenu (käyttäjätunnuksen tilalle tekijän nimi), 
    EventTool.NODE_MODES, NodeFactory.NODE_TYPE, OwnPageView ja
    ScheduleInfoTab.
  - Olisiko luokan PaattiQueryDelegate metodille removeRow parempi
    nimi setRowRemoved?
  - Olisiko luokan PaattiResearchDBService metodille 
    removeRowFromTable parempi nimi setRowRemovedFromTable?
  - Kannattaisiko tarkentaa luokan UserGroup kuvausta?

Metodien kuvauksia uupuu seuraavista luokista:
  - BelongsQueryDelegate: getQueryStatement ja StoreRow,
  - ChoiceQueryDelegate: getQueryStatement ja getCountStatement,
  - EventsInScheduleDelegate: storeRow, getQueryStatement,
  - PaattiDBService: removeUserFromGroup (vain TODO-huomio),
  - TaskQueryDelegate: storeRow,
  - UserGroup: setUsergroupResearchID sekä
  - UserGroupRolesAndResearchDelegate: getQueryStatement, storeRow.

Mahdollisesti puutteellinen tai virheellinen metodin kuvaus on 
seuraavissa luokissa:
  - BelongsQueryDelegate: setRowValues,
  - PaattiDBService: metodissa getSQLContainerFromDBTableFiltered
    on kommentti suomeksi,
  - PaattiQueryDelegate: storeRow, 
  - PaattiQueryDelegate: useampi metodi,
  - UserGroup: getUsergroupResearchID, get vai set,
  - UserGroupRolesAndResearchDelegate: setQueryStatement,
  - UserUnfinishedEventDelegate: storeRow,
  - PaattiDatabaseUtils: storeRow,
  - ApplicationTabSheet: getPaattiApplication,
  - PaattiResearch: buttonClick (itse käyttötarkoitus uupuu) sekä
  - PaattiResearchApplication: onRequestStart, onRequestEnd.

Mahdollisesti puutteellinen parametrin tai paluuarvon kuvaus on 
seuraavien luokkien metodeissa:
  - PaattiDBService: useampi metodi,
  - PaattiMobileDBService: getSQLContainerFromDBTable, 
    saveEventTaskData,
  - PaattiQueryDelegate: useampi metodi,
  - PaattiResearchDBService: createSchedule,
  - UserGroupRolesAndResearchDelegate: setRowValues,
  - UserUnfinishedEventDelegate: storeRowValues, getQueryStatement,
  - PaattiDatabaseUtils: setRowValues, getQueryStatement,
  - PaattiLoginUtils: TryLoginWithCookies, deleteLoginCookie,
  - ApplicationTabSheet: Constructor, setActiveTab,
  - ApplicationView: useampi metodi,
  - PaattiResearch: getNodeByRealIdbuttonClick,
  - LoginWindow: Constructor sekä
  - PaattiResearch: getThemeResource.

Välttämättä kaikkia eo. mahdollisia puutteita tai virheitä ei 
kannata korjata. Voisitteko kuitata ne, joita ei kannata
huomioida.

Kirjasin paperikappaleisiin palautteeksi joitain mahdollisia
kirjoitusvirheitä lähinnä artikkeleihin, verbien yksikön 
kolmannen persoonan s-kirjaimeen ja of-genetiiviin liittyen. 
Suosittelen käymään palautteeni läpi, mutta ko. huomioitani 
ei kannata alkaa korjaamaan. Toimitan tarkemman palautteeni
vartin sisällä projektihuoneeseen.

Terveisin,
               jukka-pekka

-- 
#  Jukka-Pekka Santanen (PhD, Mr)    #  santanen_at_mit.jyu.fi
#  Department of Mathematical        #  http://www.mit.jyu.fi/santanen/
#  Information Technology            #
#  University of Jyvaskyla           #  Room: Agora AgC418.2
#  P.O. Box 35 (Agora)               #  Phone: +358- (0)40 8053299
#  FIN-40014 University of Jyvaskyla #  
Received on 25.05.12 19:13:24

Tämän arkiston loi hypermail 2.2.0 : 25.05.12 19:13:26 EEST