Convenzioni per la programmazione in Visual Basic

Note: questo articolo è stato tratto da
MSDN - Visual Basic Programming Conventions from Microsoft Consulting Services
Tradotto e riadattato in alcune parti.
Non è quindi da intendersi come documentazione ufficiale.

1. Convenzioni sui nomi.

1.1 Obiettivi

• Per aiutare i programmatori (specialmente in progetti di gruppo) standardizza e decodifica la struttura e la logica di un'applicazione.
  
• Per essere precisi, completi, leggibili, semplici da ricordare e non ambigui.
  
• Per essere coerenti con le convenzioni di altri linguaggi (most importantly the Visual Basic™ Programmer's Guide and standard Microsoft® Windows™ Hungarian C)
  
• Per essere efficienti dal dimensionamento di una stringa alla visuale dell'intero progetto fino alla definizione di nomi complessi per tutti gli oggetti.
  
• Per definire il minimo indispensabile per ottenere tutto questo.

1.2 Convenzioni

1.2.1 Option Explicit

1.2.2 Denominazione dei Controlli

* Nota del traduttore *

Ulteriori estensioni verranno aggiunte man mano.

1.3 Note per il Prefisso dei Controlli

1.3.1 Menu

Per ridurre il numero di menu elencati un eccessivo sparpagliamento del codice è possibile definire un array di menu per tutte le voci dello stesso livello.
In questo caso la denominazione segue le stesse regole di cui sopra omettendo però la parte finale del nome.
Gli indici verranno identificati da costanti con prefisso "MNU_" e il relativo codice sarà gestito nell'evento click tramite una Select.

Esempi:

1.3.2 Altri controlli

1.3.3 Denominazione di variabili e routine

* Nota del traduttore *

E' consigliato l'uso del descrittore As Tipo nella dichiarazione, anzichè il carattere di tipo.
Le variabili devono sempre essere tipizzate anche se dichiarate Variant.
L'uso del tipo Variant sarà discusso più avanti.

* Nota del traduttore *

Corretta per la ver. 32bit di VB

1.3.4 Denominazione di Constanti

• Il nome di una costante deve essere scritto in MAIUSCOLO con un underscores ("_") tra le parole.
  
• Un eventuale prefisso che denota lo scopo di una costante deve essere anteposto al nome sempre in maiuscolo e separato dal nome da un underscore
  Esempi:

1.3.5 Tipi di dato Variant

vnt1 = "10.01" : vnt2 = 11 : vnt3 = "11" : vnt4 = "x4"
vntResult = vnt1 + vnt2     ' Does vntResult = 21.01 or 10.0111?
vntResult = vnt2 + vnt1     ' Does vntResult = 21.01 or 1110.01?
vntResult = vnt1 + vnt3     ' Does vntResult = 21.01 or 10.0111?
vntResult = vnt3 + vnt1     ' Does vntResult = 21.01 or 1110.01?
vntResult = vnt2 + vnt4     ' Does vntResult = 11x4 or ERROR?
vntResult = vnt3 + vnt4     ' Does vntResult = 11x4 or ERROR?

(iVar1 = 5 + val(sVar2)     'use this
vntVar1 = 5 + vntVar2       'not this!

Sub ConvertNulls(rvntOrg As Variant, rvntSub As Variant)
 'If rvntOrg = Null, replace the Null with rvntSub
   If IsNull(rvntOrg) Then rvntOrg = rvntSub
End Sub

2. Commenti

• Tutte le procedure devono iniziare con una breve descrizione delle caratteristiche funzionali.
  Questa descrizione NON deve dire come è implementata la routine, poichè questo può variare nel tempo portando a perdite di tempo nel rivedere i commenti e soprattutto a commenti erronei
  Il codice stesso e ogni eventuale suo commento descriverà l'implementazione.
  I parametri devono essere descritti se (a) sono di dubbia interpretazione (questo non dovrebbe mai accadere) (b) richiedono dei valori specifici per il funzionamento della funzione (c) il valore viene modificato all'interno della routine (questo dovrebbe accadere solo se il parametro modificato è un valore di ritorno richiesto: nessuna funzione deve prendersi la libertà di modificare il valore dei parametri che non devono restituire un valore)
  
• Ogni variabile di dubbia utilità deve essere commentata.
  
• I nomi di variabili, funzioni, controlli e quant'altro deve essere chiaro a sufficieza.
  
  Note: la Project window descrive solo i files nel progetto, quindi tutti i files esterni (come INI, DB ecc...) dovrebbero essere descritti.

3. Formattazione del Codice

Function iFindUser (rasUserList() as String, rsTargetUser as String) as Integer 
 	' Search UserList and if found, return index of first occurrence of TargetUser, 
 	' else return -1
    Dim i as Integer                    'loop counter
    Dim bFound as Integer               'target found flag
    iFindUser = -1
    i = 0
    While i <= Ubound(rasUserList) and Not bFound
       If rasUserList(i) = rsTargetUser Then 
          bFound = True
          iFindUser = i
       End If
    Wend
End Function

• Variabili e costanti devono risiedere nella sezione "Dichiarazioni" raggruppare per scopo/utilità.
• Tutte le dichiarazioni globali dovrebbero risiedere in un modulo comune.
• * nota dell'organizzatore *
  Le dichiarazioni delle variabili e costanti dovrebbero seguire il seguente ordine:
  • public const
  • public enum
  • public type
    
    
  • private const
• private enum
• private type
  
  
• public
• private / dim
• Declare
  

4. Operatori

• Usare SEMPRE "&" quando si concatenano stringhe e "+" lavorando con valori numerici.
  L'uso del solo "+" può portare a problemi lavorando con due variabili (specie con i variant).
  Per esempio:

vntVar1 = "10.01"
vntVar2 = 11
vntResult = vntVar1 + vntVar2  'vntResult = 21.01 
vntResult = vntVar1 & vntVar2  'vntResult = 10.0111

5. Scope

• Le variabili vanno sempre definite con il più piccolo scope possibile.
  Variabili globali possono creare enormi e complessi stati di macchina e rendere incomprensibile la logica di un'applicazione.
  Inoltre rendono il riuso e il mantenimento del codice molto più complesso.
  Se vengono usate variabili globali vanno tenute raggruppate per funzionalità e commentate bene.
  
• Con l'eccezione di variabili globali che non dovrebbero essere passate, le funzioni DEVONO lavorare SOLO con ciò che gli è stato passato.
  Variabili globali che devono essere passate alle funzioni devono essere commentate adeguatamente.
  
• Segmenta la logica dell'applicazione in blocchi il più possibile.
  Questo aiuterà a suddividere la complessità dell'applicazione e a minimizzare il suo run-time everhead.