[ Pobierz całość w formacie PDF ]
.The appropriate use of conventionsin referencing objects can contribute a lot to the clarity ofyour overall script.Procedure DeclarationsBy now you've seen many illustrations of how clear documentationand a consistent approach pay off.These same benefits hold truefor procedure declarations as well.Several different areas ofprocedure conventions are important.Descriptive Namesfor ProceduresOnce again, descriptive names are the first step to a good, consistentapproach.Because procedures carry out some action, the descriptivenames have a slightly different focus.Procedure names shouldbegin with an action word.If you saw a code statement that madea call to a procedure named GPA,it might not mean that much to you.Even if you realized thatGPA stands for grade pointaverage, you don't know whether this procedure displays a student'sgrade point average or prompts them for it or performs some otheractivity.A better name for the procedure can make its intent very clear.It is no surprise that a procedure named CalculateGPAcalculates a student's grade point average.This is one of thestandard areas that you should never bypass.If a procedure doesnot start with an action word, the description name is generallynot adequate.Procedure names, like variable names, should appearin mixed case to improve readability of the word components thatmake up the name.Prefixes for ProceduresPrefixes indicating data subtypes of return codes are not generallyused for procedures, although in some cases, this could add furtherclarity.Declaring functions with the appropriate prefix of thetype of data that they are to return makes those function nameseven more descriptive.Because a programmer commonly refers tofunction description comments when reviewing function call statements,good comments usually suffice.Procedure CommentsA procedure declaration should have a comment line that summarizesin one brief sentence the purpose of that procedure.There shouldalso be a comment line that describes any arguments whose purposeis not immediately obvious from the arguments' names.Then youshould have a line that specifically describes return values fromthe function if this is a function type procedure.It is importantto document the return value for error conditions as well as normalconditions when appropriate.Following these comment lines shouldappear another descriptive block of comments for procedures thatare of substantial size or complexity.The description area explainsin detail the logic or algorithm of the procedure.When writing these comments, the programmer should keep in mindthat the reader of the comments will already know VBScript.Youshould make this assumption when writing comments to avoid unnecessarilyover-commenting or adding comments of little value.For example,you don't need to describe the manner in which a For…Nextloop works just because a For…Nextloop appears within the algorithm.You have to make some basicassumptions about the programming level of the reader; otherwise,you would end up writing a book like this with each program!Although the intrinsic VBScript syntax is a well-defined, finitetopic that you can expect the comment reader to understand, controlusage is not.There is no limit in sight to the number of controlsthat might evolve, and you shouldn't assume that your commentreader is aware of anything other than the basic ActiveX controlssuch as those covered in this book.Although it is a good hunchto assume that your reader knows VBScript, it is not a safe hunchto assume that your reader knows the usage of every control thatyour code references.If your code uses an ActiveX control, thereader of your comments and code might not be familiar with thatcontrol's functionality, properties, or methods.For that matter,if you are making a change to your script a year after it waswritten, you might not remember the characteristics of a controlif it is one you don't use very frequently.For this reason, it is appropriate to document in your commentsany special uses of a control within the script.Descriptive commentsare perhaps more subjective than any other standards area.A brief,well-done description can save time over the code maintenancelife of a script
[ Pobierz całość w formacie PDF ]