Coding Conventions - Microsoft® Visual Basic® Scripting Edition

Microsoft® Visual Basic® Scripting Edition
Συμβατικοί κανόνες κωδικοποίησης

Τι είναι οι Coding conventions

Οι Coding Conventions είναι προτάσεις που μπορεί να σας βοηθήσουν να γράψετε κώδικα χρησιμοποιώντας τη Visual Basic Scripting Edition της Microsoft. μπορεί να περιέχουν τα ακόλουθα :

Ονομαστικές συμβάσεις για αντικείμενα, μεταβλητές και διαδικασίες.
Συμβάσεις σχολιασμού
Οδηγίες διαμόρφωσης και παραγραφοποίηση κειμένων

Ο κυριότερος λόγος για τον οποίο πρέπει να χρησιμοποιήσετε μια περιεκτική ομάδα από όλες αυτές τις συμβάσεις, είναι για να σταθεροποιήσετε τη δομή και το στυλ του ή των κειμένων σας ώστε και εσείς και όλοι οι άλλοι να είστε σε θέση να διαβάσετε και να καταλάβετε πιο εύκολα και πιο σωστά τον κώδικα.

Χρησιμοποιώντας καλούς συμβατικούς όρους τα αποτελέσματα στην ακρίβεια και ανάγνωση του κώδικά σας θα είναι θεαματικά.

Συμβάσεις που χρησιμοποιούνται για την ονομασία σταθερών

Τα ονόματα των σταθερών πρέπει να έχουν παύλες ( _ ) μεταξύ των λέξεων. Για παράδειγμα :

USER_LIST_MAX

NEW_LINE

Συμβάσεις που χρησιμοποιούνται για την ονομασία μεταβλητών

Προκειμένου το κείμενό σας να είναι ευανάγνωστο, περιεκτικό και ακριβές, χρησιμοποιήστε τα προθέματα που βρίσκονται στον παρακάτω πίνακα, μαζί με διάφορα περιγραφικά ονόματα για τις μεταβλητές μέσα στον κώδικα της VBScript

ΥΠΟΤΥΠΟΣ ΠΡΟΘΕΜΑ ΠΑΡΑΔΕΙΓΜΑ

Boolean bln BlnFound

Byte byt BytRasterData

Date(Time) dtm DtmStart

Double dbl DblTolerance

Error err ErrOrderNum

Integer int IntQuantity

Long lng LngDistance

Object obj ObjCurrent

Single sng SngAverage

String str StrFirstName

Εμβέλεια των μεταβλητών

Οι μεταβλητές θα πρέπει πάντα να προσδιορίζονται με τη μικρότερη δυνατή έκταση. Οι μεταβλητές στη VBScript μπορούν να έχουν την παρακάτω έκταση :

ΕΜΒΕΛΕΙΑ ΠΟΥ ΔΗΛΩΝΕΤΑΙ Η ΜΕΤΑΒΛΗΤΗ ΟΡΑΤΟΤΗΤΑ

Επίπεδο διαδικασίας Event,Function ή Sub διαδικασία Ορατή στη διαδικασία μέσα στην οποία έχει δηλωθεί.

Επίπεδο κειμένου Στο HEAD τμήμα μιας σελίδας HTML εξω απο κάθε διαδικασία Ορατή σε κάθε διαδικασία μέσα στο κείμενο.

Εμβέλεια των προθεμάτων των μεταβλητών

Ένα πρόθεμα ενός μόνο γράμματος διατηρεί τον κλασσικό τύπο του προθέματος και ταυτόχρονα δίνει μεγαλύτερη ευελιξία στα ονομάτα των μεταβλητών.

ΕΜΒΕΛΕΙΑ ΠΡΟΘΕΜΑ ΠΑΡΑΔΕΙΓΜΑ

Επιπεδο διαδικασίας Κανένα dblVelocity

Επίπεδο κειμένου s sblnCalcInProgress

Περιγραφικές μεταβλητές και ονόματα διαδικασιών

Το σώμα, το κύριο μέρος του ονόματος μιας μεταβλητής ή μιας διαδικασίας, θα πρέπει να είναι όσο πιο περιεκτικό και πλήρες γίνεται προκειμένου να εξυπηρετεί σωστά το σκοπό του. Επιπρόσθετα οι ονομασίες των διαδικασιών θα πρέπει να ξεκινούν μ’ ένα ρήμα όπως π.χ. IntNameArray ή CloseDialog.

Για εκείνες τις ονομασίες που χρησιμοποιούνται συχνά ή αποτελούνται από μεγάλους σε μήκος όρους, προτείνονται διάφορες συντμήσεις ώστε να διατηρούνται οι ονομασίες σ’ ένα λογικό μήκος. Γενικά όταν τα ονόματα των μεταβλητών ξεπερνούν τους 32 χαρακτήρες, είναι δύσκολο να διαβαστούν.

Όταν χρησιμοποιείτε συντμήσεις ή και συντομογραφίες σιγουρευτείτε ότι είναι περιεκτικοί καθ’ όλο το μήκος του κειμένου σας. Για παράδειγμα αν χρησιμοποιείτε συχνά μια το Cut και μια το Count καθώς το ή τα set του κειμένου σας τρέχουν, μπορεί να οδηγηθείτε σε ένα αδιέξοδο, μια σύγχυση.

Οι συμβατικοί όροι που χρησιμοποιούνται στην ονομασία αντικειμένων.

Ο παρακάτω πίνακας περιέχει διάφορους συμβατικούς όρους για τα ποικίλα αντικείμενα που μπορεί να συναντήσετε ενώ προγραμματίζετε στο VBScript.

ΤΥΠΟΣ ΑΝΤΙΚΕΙΜΕΝΟΥ	ΠΡΟΘΕΜΑ	ΠΑΡΑΔΕΙΓΜΑ
3D Panel	pnl	pnlGroup
Animatted Button	ani	aniMailBox
Check Box	chk	chkReadOnly
Combo box, drop-down list box	cbo	cboEnglish
Command button	cmd	cmdExit
Common dialog	dlg	dlgFileOpen
Frame	fra	fraLanguage
Horizontal scroll bar	hsb	hsbVolume
Image	ing	imgIcon
Label	lbl	lblHelpMessage
Line	lin	linVertical
ListBox	lst	lstPolicyCodes
Spin	spn	spnPages
Text box	txt	txtLastName
Vertical scroll bar	vsb	vsbRate
Slider	sld	sldScale

Οι συμβατικοί όροι που τηρούνται για το σχολιασμό του κώδικα

Όλες οι διαδικασίες θα πρέπει να ξεκινούν μ’ ένα σύντομο σχόλιο περιγράφωντας τί κάνουν. Το σχόλιο αυτό δε θα πρέπει να περιγράφει τις λεπτομέρειες εφαρμογής (πώς ακριβώς λειτουργεί μια διαδικασία) γιατί αυτή αλλάζει κάθε τόσο και γιατί κάτι τέτοιο θα οδηγούσε είτε σε μια ανούσια εμμονή στο συγκεκριμένο σχόλιο είτε σε λανθασμένες οδηγίες. Ο κώδικας από μόνος του μαζί με κάθε απαραίτητο σχόλιο που αυτός περικλείει, αναλύει και περιγράφει ακριβώς την εφαρμογή.

Τα ορίσματα που βρίσκονται μέσα σε μια διαδικασία θα πρέπει να περιγράφονται όταν ο σκοπός της χρήσης τους δεν είναι εμφανής ή όταν η διαδικασία τα θέλει να κυμαίνονται σ’ ένα συγκεκριμένο εύρος. Διάφορες συναρτήσεις που επιστρέφουν τιμές όπως και άλλες μεταβλητές που αλλάζονται από τη διαδικασία, όπως τα ορίσματα, θα πρέπει επίσης να περιγράφονται στην αρχή της κάθε διαδικασίας.

Τα σχόλια που προηγούνται της διαδικασίας θα πρέπει να ακολουθούν τις ακόλουθες επικεφαλίδες. Για περισσότερα παραδείγματα παρατηρείστε το κείμενο που ακολουθεί

ΕΠΙΚΕΦΑΛΙΔΑ ΤΜΗΜΑΤΟΣ ΣΧΟΛΙΑΣΜΟΣ ΤΩΝ ΠΕΡΙΕΧΟΜΕΝΩΝ

Purpose (Σκοπός) Τί κάνει η διαδικασία (όχι πώς).

Assumptions (Υποθέσεις) Μια λίστα με οποιαδήποτε εξωτερική μεταβλητή ή άλλο στοιχείο των οποίων η κατάσταση επηρεάζει τη συγκεκριμένη διαδικασία.

Effects (Αποτελέσματα) Μια λίστα με όλα τα αποτελέσματα που έχει η διαδικασία πάνω σε κάθε εξωτερική μεταβλητή ή άλλο στοιχείο.

Inputs (Εισερχόμενα) Εξήγηση και αναλυτική περιγραφή για το κάθε όρισμα του οποίου η χρήση δεν είναι εμφανής. Κάθε όρισμα θα πρέπει να αναλύεται σε ξεχωριστή γραμμή με ενσωματωμένα κάθε φορά σχόλια.

Return Values (Επιστροφή τιμών) Εξήγηση για την κάθε τιμή που επιστρέφεται.

Θυμηθείτε τα παρακάτω σημεία :

Κάθε δήλωση μιας σημαντικής μεταβλητής θα πρέπει να εμπεριέχει σχόλια που θα περιγράφουν αναλυτικά τη χρήση της.
Οι μεταβλητές οι έλεγχοι και οι διαδικασίες θα πρέπει να ονομάζονται και να δηλώνονται τόσο ξεκάθαρα ωστε τα σχόλια που θα ακολουθούν να περιέχουν μόνο τις πολύπλοκες λεπτομέρειες εφαρμογής.
Στην αρχή του κειμένου σας θα πρέπει να συμπεριλάβετε μια έκθεση η οποία θα περιγράφει το κείμενο, θα απαριθμεί τα αντικείμενα, τις διαδικασίες, τους αλγόριθμους, τα κουτιά διαλόγου και τα υπόλοιπα περιεχόμενα του συστήματος. Μερικές φορές απλά και μόνο ένα κομμάτι ενός ψευτοκώδικα που θα περιγράφει τον αλγόριθμο, που θα περιγράφει τον αλγόριθμο μπορεί να βοηθήσει και να φανεί πολύ χρήσιμο.

Διαμορφώνοντας τον κώδικά σας Ο χώρος της οθόνης θα πρέπει να διατηρείται όσο το δυνατόν περισσότερο, ενώ θα πρέπει ταυτόχρονα να επιτρέπει στη φόρμα του κώδικά σας να αντανακλά μια λογική δομή και δικτύωση. Παρακάτω δίνονται μερικά βοηθητικά στοιχεία.

Τα στάνταρ nested blocks θα πρέπει να εισχορούν 4 διαστήματα.
Τα σχόλια μιας διαδικασίας θα πρέπει να απέχουν ένα διάστημα.
Τα σχόλια υψηλότερου επιπέδου που ακολουθούν τα παραπάνω θα πρέπει να απέχουν μεταξύ τους 4 διαστήματα με επιπρόσθετα 4 κενά για κάθε nested block που εμπεριέχεται σ’ αυτά. Για παράδειγμα :

*********************************************************************

Purpose (Σκοπός): Εντοπίζει το πρώτο συμβάν ενός συγκεκριμένου χρήστη, στον πίνακα UserList.

Inputs (Εισερχόμενα): strUserList (): Η λίστα με τους χρήστες που πρόκειται να αναζητηθεί.

strTargetUser: Το όνομα του χρήστη που αναζητείται.

Returns (Επιστρέφει): Τα περιεχόμενα και το κείμενο του πρώτου συμβάντος του strTargetUser, μέσα στον πίνακα strUserList.

Αν δεν έχει βρεθεί ο χρήστης που αναζητείται, επιστρέφεται -1.

*********************************************************************

Function intFindUser (strUserList(), strTargetUser)

Dim I ‘ Loop counter.

Dim blnFound ‘ Target found flag

intFindUser = -1

i = 0 ‘ Initialize loop counter

Do While I < = Ubound (strUserList) and Not blnFound

If strUserList (i) = strTargetUser Then

blnFound = True ‘ Set flag to True

intFindUser = I ‘ Set return value to loop count

End If

i = i +1 ‘ Increment loop counter

Loop

End Function

ΥΠΟΤΥΠΟΣ	ΠΡΟΘΕΜΑ	ΠΑΡΑΔΕΙΓΜΑ
Boolean	bln	BlnFound
Byte	byt	BytRasterData
Date(Time)	dtm	DtmStart
Double	dbl	DblTolerance
Error	err	ErrOrderNum
Integer	int	IntQuantity
Long	lng	LngDistance
Object	obj	ObjCurrent
Single	sng	SngAverage
String	str	StrFirstName

ΕΜΒΕΛΕΙΑ	ΠΟΥ ΔΗΛΩΝΕΤΑΙ Η ΜΕΤΑΒΛΗΤΗ	ΟΡΑΤΟΤΗΤΑ
Επίπεδο διαδικασίας	Event,Function ή Sub διαδικασία	Ορατή στη διαδικασία μέσα στην οποία έχει δηλωθεί.
Επίπεδο κειμένου	Στο HEAD τμήμα μιας σελίδας HTML εξω απο κάθε διαδικασία	Ορατή σε κάθε διαδικασία μέσα στο κείμενο.

ΕΠΙΚΕΦΑΛΙΔΑ ΤΜΗΜΑΤΟΣ	ΣΧΟΛΙΑΣΜΟΣ ΤΩΝ ΠΕΡΙΕΧΟΜΕΝΩΝ
Purpose (Σκοπός)	Τί κάνει η διαδικασία (όχι πώς).
Assumptions (Υποθέσεις)	Μια λίστα με οποιαδήποτε εξωτερική μεταβλητή ή άλλο στοιχείο των οποίων η κατάσταση επηρεάζει τη συγκεκριμένη διαδικασία.
Effects (Αποτελέσματα)	Μια λίστα με όλα τα αποτελέσματα που έχει η διαδικασία πάνω σε κάθε εξωτερική μεταβλητή ή άλλο στοιχείο.
Inputs (Εισερχόμενα)	Εξήγηση και αναλυτική περιγραφή για το κάθε όρισμα του οποίου η χρήση δεν είναι εμφανής. Κάθε όρισμα θα πρέπει να αναλύεται σε ξεχωριστή γραμμή με ενσωματωμένα κάθε φορά σχόλια.
Return Values (Επιστροφή τιμών)	Εξήγηση για την κάθε τιμή που επιστρέφεται.