Università degli studi di Modena e Reggio Emilia
progetto e-COM

convenzioni per i nomi

Premesse

1. L’uso di nomi standardizzati aumenta grandemente le possibilità di manutenere, condividere e sviluppare applicazioni in gruppo.

2. Se avete provato a mettere le mani su un applicativo sviluppato da un altro, conoscete la frustrazione di capire il suo stile e il tempo che ci vuole per fare manutenzione su uno stile diverso dal vostro. Ma anche il vostro stile cambia nel tempo e dopo qualche anno anche il vostro codice vi risulterà estraneo come quello scrito da un altro.

C’è quindi una sola ragione per non adottare convenzioni: tenere nascosta la logica dell’applicazione: agli altri perché sia difficile copiare e a voi stessi per farvi pagare le giornate di manutenzione.

Dunque scegliete: volete essere pagati per mantenere software casalingo, unico al mondo e chiuso nel vostro cassetto o per produrre software aperto, riutilizzabile, fruibile da tutti? State tranquilli, ci sarà sempre nuovo software da produrre!

3. Il metodo qui descritto è chiamato ungherese (hungarian) dalla nazionalità del creatore, Charles Simonyj ed è stato pubblicato da Stan Leszynski e Greg Reddick per la prima volta nel 1993. Ecco il documento originale:

http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnaccgen/html/msdn_20naming.asp

Prevede due livelli: il livello 1 è completo, ma non esplicita gli oggetti come il livello 2, che consente di ordinare insieme funzioni simili in basi di dati di grandi dimensioni.

 

Struttura dei nomi

[prefissi]tag[NomeBase][Qualificatori]

Le parentesi indicano opzionalità e non fanno parte del nome. Può sembrare strano che l’unica parte obbligatoria sia il tag, ma questo consente di fare riferimento a oggetti generici, quando sono passati come parametri.

I prefissi e i tag sono minuscoli, così l’occhio li può oltrepassare in fretta, fino alla prima lettera maiuscola, che inizia il nome base. Il nome base (che rappresenta l’oggetto e non la classe) si compone di una o più parole: non si devono utilizzare spazi bianchi, ma si deve utilizzare la maiuscola all’inizio di ogni parola (se proprio non se ne può fare a meno, usare _). Infine il nome base deve essere singolare, anche se si tratta di una tabella (infatti in questo caso il plurale è implicito).

Il nome base di una tabella deve prevalere, cioè gli oggetti che che si riferiscono direttamente alla tabella devono avere lo stesso nome base e diverso tag.

Oggetti di database

	oggetto	tag	esempio
livello 1	Table	tbl	tblCustomer
	Table (lookup)	tlkp	tlkpShipper
livello 1	Query (select)	qry	qryOverAchiever
	Query (append)	qapp	qappNewProduct
	Query (crosstab)	qxtb	qxtbRegionSales
	Query (data definition)	qddl	qddlAddWorkColumn
	Query (delete)	qdel	qdelOldAccount
	Query (form filter)	qflt	qfltSalesToday
	Query (lookup)	qlkp	qlkpStatus
	Query (make table)	qmak	qmakShipTo
	Query (pass-through)	qspt	qsptArchiveQuantity
	Query (union)	quni	quniOrderDetail
	Query (update)	qupd	qupdDiscount
livello 1	Form	frm	frmCustomer
	Form (dialog)	fdlg	fdlgLogin
	Form (menu)	fmnu	fmnuUtility
	Form (message)	fmsg	fmsgWait
	Form (subform)	fsub	fsubOrder
livello 1	Report	rpt	rptInsuranceValue
	Report (subreport)	rsub	rsubOrder
livello 1	Macro	mcr	mcrUpdateInventory
	Macro (for form)	m[formname]	mfrmCustomer
	Macro (menu)	mmnu	mmnuEntryFormFile
	Macro (for report)	m[rptname]	mrptInsuranceValue
livello 1	Module	bas	basBilling

Il solo qualificatore previsto è Sub.

I prefissi consentono di mantenere gli oggetti in cima e in fondo all’ordinamento alfabetico:

zz	oggetti abbandonati, ma che si vuole conservare
zt	oggetti temporanei
zs	oggetti di sistema, cioè oggetti non usati dall’utente, ma utili per lo sviluppo e la manutenzione
_	oggetti in sviluppo

Campi

 

L’uso dei tag nei nomi dei campi è un tema caldo, perché alcuni sostengono che i nomi dei campi devono essere indipendenti dal tipo del dato, per mantenere puro lo schema del database. Ma i vantaggi dell’uso del tag rimengono forti.

Field Type	Tag	Example
Binary	bin	binInternal
Byte	byt	bytFloorNum
Counter	lng	lngPKCnt
Currency	cur	curSalary
Date/Time	dtm	dtmHireDate
Double	dbl	dblMass
Integer	int	intUnit
Long	lng	lngPopulation
Memo	mem	memComments
Ole	ole	oleEmpPhoto
Single	sng	sngScore
Text	str	strFirstName
Yes/No	ysn	ysnDiscounted

I contatori sono di tipo long: se si vuole distinguere la loro specifica natura, utilizzare il suffisso cnt.

Controlli

Object	Tag	Example
Label	lbl	lblLastName
Control (generic)	ctl	ctlLastName
Chart (graph)	cht	chtSales
Check box	chk	chkReadOnly
Combo box	cbo	cboIndustry
Command button	cmd	cmdCancel
Frame (object)	fra	fraPhoto
Line	lin	linVertical
List box	lst	lstPolicyCode
Option button	opt	optFrench
Option group	grp	grpLanguage
Page break	brk	brkPage1
Rectangle/shape	shp	shpNamePanel
Subform/report	sub	subContact
Text box	txt	txtLoginName
Toggle button	tgl	tglForm

C’è un solo prefisso per i controlli: zs, che denota controlli di sistema, non visibili all’utente, che possno memorizzare valori temporanei o parametri passati.

Procedure

Per una funzione chiamata da una proprietà di una form, utilizzare:

formname_controlname_propertyname for example: frmEmployee_cmdAdd_Push

Per una proprietà che si riferisce a un’intera form, utilizzare:

formname_propertyname, as in frmEmployee_Open.

Se due o più controlli di una form eseguono lo stesso codice, creare una funzione per ognuno, da cui chiamare un’unica funzione che contiene il codice comune.

Variabili

Variable Type	Tag	Example
Container	con	Dim conTables as Container
Control	ctl	Dim ctlVapor As Control
Currency	cur	Dim curSalary As Currency
Database	db	Dim dbCurrent As Database
Document	doc	Dim docRelationships as Document
Double	dbl	Dim dblPi As Double
Dynaset	dyn	Dim dynTransact As Dynaset
Flag (Y/N, T/F)	f	Dim fAbort As Integer
Field	fld	Dim fldLastName as Field
Form	frm	Dim frmGetUser As Form
Group	gru	Dim gruManagers as Group
Index	idx	Dim idxOrderId as Index
Integer	int	Dim intRetValue As Integer
Long	lng	Dim lngParam As Long
Object	obj	Dim objGraph As Object
Parameter	prm	Dim prmBeginDate as Parameter
Property	prp	Dim prpUserDefined as Property
QueryDef	qdf (or qrd)	Dim qdfPrice As QueryDef
Recordset	rec (or rst)	Dim recPeople as Recordset
Relation	rel	Dim relOrderItems as Relation
Report	rpt	Dim rptYTDSales As Report
Single	sng	Dim sngLoadFactor As Single
Snapshot	snp	Dim snpParts As Snapshot
String	str	Dim strUserName As String
Table	tbl	Dim tblVendor As Table
TableDef	tdf (or tbd)	Dim tdfBooking as TableDef
Type (user-defined)	typ	Dim typPartRecord As mtPART_RECORD
User	usr	Dim usrJoe as User
Variant	var	Dim varInput As Variant
Workspace	wrk (or wsp)	Dim wrkPrimary as Workspace
Yes/No	ysn	Dim ysnPaid As Integer

Lo stile proposto non usa i suffissi $ e % perché sono scoraggiati dalla Microsoft.

I tag per le variabli sono gli stessi usati per gli oggetti.

Per le constanti e tipi definiti dall’utente

Si può usare anche la convenzione molto diffusa del tutto maiuscolo, ma si deve usare il prefisso typ e i prefissi g ed m (vedi sotto).

Il livello 2 propone prefissi per lo scope di variabili e costanti.

Questi prefissi vanno anteposti agli altri prefissi.

Le variabili dichiarate localmente con Dim non hanno prefisso

Le variabili dichiarate localmente con Static hanno prefisso s (es.: sintAccumulate)

Le variabili dichiarate in un modulo con Dim hanno prefisso m (es.: mcurRunningSum)

Le variabili dichiarate con Global hanno prefisso g (es.: glngGrandTotal)

Le variabili che denotano parametri passati a una funzione (tra parentesi dopo il nome della funzione) hanno prefisso r se passati per referenza o v se passati per valore

I qualificatori (che seguono il nome della variabile e lo differenziano ulteriormente) dipendono dall’applicazione e possono essere creati ad hoc. Si riporta una lista dei più comuni.

Variable Property	Qualifier	Example
Current element of set	Cur	iaintCur
First element of set	First	iaintStockFirst
Last element of set	Last	iaintStockLast
Next element of set	Next	strCustomerNext
Previous element of set	Prev	strCustomerPrev
Lower limit of range	Min	iastrNameMin
Upper limit of range	Max	iastrNameMax
Source	Src	lngBufferSrc
Destination	Dest	lngBufferDest

Labels

Si usa un qualificatore del nome della funzione per creare label standard. Per esempio per l’istruzione On Error GoTo, si usa il nome della funzione con il qualificatore _Err.

Bisogna creare una label per saltare alla fine della funzione, perché è più appropriato avere un solo punto d’uscita dalla funzione (per assicurara una omogenea chiusura di file e settaggio di variabili), invece di cospargere ovunque le istruzioni di Exit. Utilizzare il qualificatore _Done, come in cmdAdd_Click_Done.

Nomi e commenti

La convenzione sui nomi non sostituisce i commenti: seplicemente è un’altra tecnica di buona programmazione.

In ogni modulo deve essere indicato, perlomeno: obiettivo, autore, data, parametri, ultima revisione e relative note.