home *** CD-ROM | disk | FTP | other *** search
/ Media Share 9 / MEDIASHARE_09.ISO / progmisc / dblib201.zip / DHUNG2.TXT < prev    next >
Text File  |  1993-03-24  |  18KB  |  448 lines

  1.                                 dUFLP/dHUNG
  2.                      Coding Standards and Conventions
  3.                                 Version 0.7
  4.                               April 17, 1992
  5.  
  6.  
  7. dUFLP -- dBASE Users Function Library Project -- Coding Standards and
  8. Conventions -- Based upon the HUNGARIAN / xBase Conventions by Robert A.
  9. DiFalco. These Standards and Conventions have been defined and generally
  10. agreed upon by several of the 'regulars' on the Borland (once Ashton-Tate)
  11. Bulletin Board System (BORBBS (now defunct)), but are by no means a rigid 
  12. definition.
  13.  
  14. This file contains modifications to Robert DiFalco's (CIS: 71610,1705)
  15. HUNG standard for X-Base languages; it was developed by members of the
  16. Ashton-Tate/Borland Bulletin Board System to be used in a user-developed
  17. library.  Several aspects of this document have been changed, as the dUFLP
  18. standards are more aimed at dBase than other programming languages, but
  19. have been only slightly modified where needed, and some duplicate
  20. definitions were removed in the variable naming practices. The original
  21. document (HUNG14.ZIP) may be found on the CompuServe dBASE Forum.
  22.  
  23. The purpose of this document is to define some coding standards to be used
  24. in the library for dUFLP, Please attempt to follow these standards as 
  25. closely as possible when creating Functions and Procedures to be included 
  26. in this library. Thank you ... (most of the text from this point on is 
  27. DiFalco's own words)
  28. ---------------------------------------------------------------------------
  29. Let me start off by stating that these are only my opinions on naming
  30. conventions for xBase programming. In my opinion these methods are
  31. extensible to C, ASM, BASIC and just about any other programming
  32. language. It looks very similar to Hungarian notation as outlined by
  33. Charles Simonyi of Microsoft Corporation. Don't be fooled, however, this is
  34. much different. I find it more intuitive and logical though that may
  35. pertain only to my thinking.
  36.  
  37. These conventions take in the same factors as outlined by Charles Simonyi
  38. for creating names in a program. The factors listed below are directly
  39. quoted from his monograph.
  40.  
  41. Begin quote:
  42. 1. Mnemonic value   - so that the programmer can remember the name.
  43.  
  44. 2. Suggestive value - so that others can read the code easily.
  45.  
  46. 3. "Consistency"    - this is often viewed as an aesthetic idea, yet it
  47.                       also has to do with the information efficiency of the
  48.                       program text. Roughly speaking, we want similar names
  49.                       for similar quantities.
  50.  
  51. 4. Speed of decision- we cannot spend too much time pondering the name of a
  52.                       single quantity, nor is there time for typing and
  53.                       editing extremely long variable names.
  54. End quote:
  55.  
  56. In dBase, our variable names have even a more pressing reason for short
  57. identifiers since we only have 10 characters to work with. To alleviate
  58. using needless characters, we will use lowerUpper combinations instead of
  59. dividing underscores.
  60.  
  61. =====================================
  62. Procedure/Function Naming conventions
  63. =====================================
  64. Procedures and Functions will be heretofore called "Functions". Function
  65. names will not be "typed" as variables. As dBase in general heads towards
  66. object oriented approaches it is important to allow our Functions to return
  67. multiple types. This negates the approach of typing Functions by return
  68. variable type. Instead we will apply a "loose" set of rules to Functions.
  69. Native language functions will be in all lowercase while 3rd party or "home
  70. grown" functions (UDF or User-Defined Functions) will be mixed case
  71. beginning with a single Capital letter.
  72.  
  73. -------------
  74. UDF Name Case
  75. -------------
  76. All User Defined Functions will be mixed case, with no underscores. The
  77. first letter will be upper case, e.g. AllTrim.
  78.  
  79. 1. Functions will start with a capital letter followed by lower case
  80.    letters thus distinguishing them from variables. If the Function name
  81.    can be better expressed by two or three identifiers an UpperLower
  82.    combination will be used rather than underscores to delimit identifiers.
  83.    Consider the following Examples:
  84.  
  85.    ClrSet()    - Sets colors
  86.    SaveGets()  - Saves active get list
  87.    PrnScr()    - Prints the screen
  88.    GetPass()   - Gets a password
  89.    Choose()    - Menu of items to "choose" from
  90.  
  91. 2. Conversion Functions will start with the value they take and end with
  92.    converted value separated by the number 2. Some examples would be as
  93.    follows:
  94.  
  95.    Str2Arr()  - Changes a string to an array.
  96.    Hex2Dec()  - Changes a Hex string into a decimal numeric.
  97.    Clr2Attr() - Changes a color string to an integer attribute.
  98.    Dbf2Arr()  - Loads a DBF into an array.
  99.  
  100. 3. Where possible, use standard qualifiers as outlined in the section
  101.    dedicated to "Variable Naming Conventions". A few examples follow.
  102.  
  103.    cFName   = HCUST->FNAME
  104.    cLName   = HCUST->LNAME
  105.    cAddr    = HCUST->ADDR
  106.    nAge     = HCUST->AGE
  107.    lActive  = HCUST->ACTIVE
  108.    nBalance = HLOAN->BALANCE
  109.    ( Please note that the storage operators ( "=" ) are lined up for easy
  110.    reading giving a table appearance. )
  111.  
  112. 4. Where possible, express the function or procedure in less than three
  113.    qualifiers ( names ). Refer to the examples given for Rule 1.
  114.  
  115. 5. The keywords PROCEDURE, FUNCTION and RETURN shall be in all uppercase.
  116.  
  117.    FUNCTION SayStr
  118.  
  119.       parameters cMsg
  120.  
  121.       xSavClr = set( "ATTRIBUTES" )
  122.       set color to rg+/r
  123.  
  124.       ? cMsg
  125.  
  126.       set color to xSavClr
  127.  
  128.    RETURN ""
  129.  
  130. dBASE native functions shall be typed in all lowercase to delineate them
  131. from non-native functions as in the above call to set(). 
  132.  
  133.  
  134. ------------------
  135. Reserved Word Case
  136. ------------------
  137. Except for the reserved words 'FUNCTION', 'PROCEDURE', and 'RETURN', all
  138. dBASE reserved words should be lower case.
  139.  
  140. -----------------------------
  141. File Name and Field Name Case
  142. -----------------------------
  143. All reference to DOS files (e.g. .dbf, .fmt, .frg, etc.) and field
  144. names are to be in upper case.  Underscores are allowed.
  145.  
  146. ------------
  147. Case Summary
  148. ------------
  149. all lower                 : built-in commands and functions
  150. mIxed, fIrst lEtTer lOWer : memvars
  151. MiXed, First LetTer UpPer : UDFs
  152. ALL UPPER                 : files and fields, and the commands
  153.                             FUNCTION, PROCEDURE, and RETURN
  154.  
  155. =============================================
  156. DBF and Field related Punctuation Conventions
  157. =============================================
  158. There are some rules noteworthy for DBF, NDX/MDX, ALIAS and FIELD
  159. operations to delineate them from Functions and Variables. FIELD names will
  160. NOT be typed by a lowercase type identifier as with Variables.
  161.  
  162. 1. Database and Index files, as well as Field names will always be
  163.    expressed in capital letters. As dBase's main point of existence is the
  164.    manipulation of DataFiles, this will make them stand out against 
  165.    variables and other qualifiers.
  166. 2. Where possible they will use the same standard qualifiers used for
  167.    Variables and Functions. See the examples for Rule 3 of
  168.    "Procedure/Function Naming Conventions".
  169.  
  170. 3. Fields will be referenced by an ALIAS. Consider the following.
  171.  
  172.    HACCT->ACCNUM
  173.    HCONST->PASSWORD
  174.    HCONST->COMPANY
  175.  
  176. 4. Variables referencing Fields will have the same name as the Field with
  177.    the addition of the dHUNG type prefix.
  178.  
  179.    cFName   = HCUST->FNAME
  180.    cLName   = HCUST->LNAME
  181.    cAddr    = HCUST->ADDR
  182.    nAge     = HCUST->AGE
  183.    lActive  = HCUST->ACTIVE
  184.    nBalance = HLOAN->BALANCE
  185.  
  186.    ( Please note that the storage operators ( "=" ) are lined up for easy
  187.      reading giving a table appearance. )
  188.  
  189. 5. With regard to DBF file names, data, index or otherwise they should
  190.    all begin with a common prefix and that prefix is similar to the
  191.    name.
  192.  
  193.    This insures that I have few naming conflicts with other systems
  194.    that may reside on the computer and just about guarantees I can
  195.    separate my files out if they get placed into a common subdirectory.
  196.  
  197. 6. Index filenames should reflect the file that they belong to but
  198.    should not attempt to indicate what the index expression is.  A
  199.    much cleaner routine results when index files are simply numbered.
  200.  
  201.    HACCTS.DBF ---> HACCTS1.NDX
  202.                    HACCTS2.NDX
  203.                    HACCTS3.NDX
  204.  
  205.    Internally the only information I am required to keep is the index key
  206.    in an array and all indexes can be rebuilt in the order of their
  207.    respective suffix number.
  208.  
  209. ===============================
  210. Command Punctuation Conventions
  211. ===============================
  212. This area of my dHUNG naming conventions will probably meet with the most
  213. opposition. User Defined Commands will use descriptive names as outlined in
  214. "Procedure/Function Naming Conventions".  User Defined or not, Commands
  215. will have one Rule.
  216.  
  217. 1. All Commands will be typed with lower case letters.
  218.  
  219. The reasons for this are simple. This will delineate commands from
  220. variables, functions and DBF elements. Consider the following examples.
  221.  
  222. FUNCTION CmdExample
  223.  
  224.    use HCUST 
  225.    set index to HCUST1, HCUST2, HCUST3
  226.  
  227.    cLName = "DiFalco"
  228.  
  229.    seek cLName
  230.  
  231.    HCUST->AGE    = 28
  232.    HCUST->ACTIVE = .t.
  233.    HCUST->LNAME  = cLName
  234.  
  235.    close database
  236.  
  237. RETURN ""
  238.  
  239. ( Please take note that in replace statements we also line up the "with"
  240.   portion of the command as we do storage operators. )
  241.  
  242. ===========================
  243. Variable Naming Conventions
  244. ===========================
  245. This is the heart of a well designed system. Variable names must give the
  246. most amount of information possible in its name while using the minimum
  247. number of characters possible.
  248.  
  249. All memory variables (memvars) are mixed case names, consisting of 1-10
  250. alphanumeric characters.  The first character is always a lower case
  251. type prefix.  Underscores are only used as scope prefixes.  Memvar names
  252. should not repeat type prefix information.
  253.  
  254. But memvars may have a combination of tags that will in most cases appear
  255. in this order.
  256.  
  257. 1. A single lower case variable defining its type as returned by a Type()
  258.    function called a "Type Prefix".
  259. 2. An Optional state called a "State Qualifier"
  260. 3. A "Standard Qualifier Tag".
  261. 4. An Optional "Pointer Reference".
  262.  
  263. -------------
  264. Type Prefixes
  265. -------------
  266. A type prefix is the first character of a variable that represents the
  267. type the programmer intends for the variable.  Below is the list of
  268. dBASE-specific type prefixes together with examples:
  269.  
  270.              Prefix          Type          Example
  271.              ------          ----          -------
  272.                 a            Array         aList
  273.                 c            Character     cFName
  274.                 d            Date          dPmtDue
  275.                 f            Float         fAngle
  276.                 l            Logical       lExitMenu
  277.                 m            Menu          mMain
  278.                 n            Numeric       nHours
  279.                 p            Pad           pOpenDbf
  280.                 s            Screen        sBackgrnd
  281.                 u            popUp         uFlds
  282.                 w            Window        wError
  283.                 x            undefined     xLookUp
  284.  
  285. For temporary variables of distinct type or pointers this single prefix can
  286. be used by itself. Consider this example.
  287.  
  288. n = 0
  289. do while n < nFldMax
  290.    n = n + 1
  291.    aFldName[n] = Field( n )
  292. enddo
  293.  
  294. --------------
  295. Scope Prefixes
  296. --------------
  297. In dBASE, a variable can be either local to a procedure or global to all
  298. procedures.  This distinction is represented by the scope prefix.
  299. Variables that are global are represented by an underscore after the
  300. type prefix; variables that are local to a procedure have a null scope
  301. prefix.  For example, c_DbfFile is a character variable that is global;
  302. cDbfFile would be the same variable if it was local.
  303.  
  304. -------------------------
  305. Sample "State Qualifiers"
  306. -------------------------
  307. New  - a New state
  308. Sav  - a Saved state
  309. Tem  - a Temporary state
  310.  
  311. --------------------------------
  312. Sample "Standard Qualifier" tags
  313. --------------------------------
  314. Attr - Attribute
  315. Clr  - Color
  316. Crs  - Cursor
  317. Dbf  - of or pertaining to a DBF
  318. F    - First as in cFName
  319. File - Any type of file
  320. Fld  - Field
  321. L    - Last as in cLName
  322. Msg  - Message
  323. Name - a name
  324. Ndx  - of or pertaining to an Index ( or Mdx )
  325. Rec  - Record Number
  326. Ret  - Return value ( lRet = .f. )
  327. Str  - String
  328. T    - Top
  329. L    - Left
  330. B    - Bottom
  331. R    - Right
  332. Row  - Row
  333. Col  - Column
  334. X    - Row
  335. Y    - Column
  336.  
  337. Please note that Standard Qualifiers can be used in combinations as in the
  338. following examples.
  339.  
  340.    nTRow    - Top Row
  341.    cFName   - First name
  342.    cDbfFile - a Database file
  343.    cNdxFile - an Index File
  344.  
  345. ---------------------------
  346. Sample "Pointer References"
  347. ---------------------------
  348. 1,2,3 - State pointer references as in cSavClr1, cSavClr2, etc.
  349. Max   - Strict upper limit as in nFldMax, maximum number of Fields
  350. Min   - Strict lower limit as in nRecMin, minimum number of Records
  351.  
  352.  
  353. These lists are to serve as samples and building blocks. They can and
  354. should be added to. Lets look at a few examples of the conventions at work.
  355. This should dispel the myth that notation conventions cannot be applied to
  356. variables with a 10 character maximum length.
  357.  
  358. ==========================================
  359. Poorly Designed and Well Designed Examples
  360. ==========================================
  361.  
  362. WRONG       RIGHT       WHY
  363. --------------------------------------------------------------------------
  364. nFldNum     nFld        Number is indicated by the Type Prefix making the
  365.                         word Num redundant and a needless use of character
  366.                         space.
  367. Count       n           n serves as a temporary count index. Count has no
  368.                         Type Prefix - could also be called nCount.
  369. Last_Name   cLName      This is one of the most horrendous mistakes. First
  370.                         we do not specify the variable type. Second we
  371.                         needlessly spell out LAST and worst of all we use
  372.                         up a precious character by using an underscore
  373.                         instead of using the UpperLower combination.
  374. SaveScreenA sSav1       No Type Prefix, needless use of characters. The
  375. SaveScreenB sSav2       alphabetical reference is allowable though I prefer
  376. SaveScreenC sSav3       to use a numeric reference. Use of 's' type prefix
  377.                         removes need to use Scrn or sScreen.
  378. ColorStr    xClr        No Type Prefix. Needless use of characters. This 
  379.                         shows the usage of 'unknown' type with the Type Prefix
  380.                         'x' (colors are character strings in specific
  381.                         formats, but do not require a special type).
  382. nRecNo      nRec        The use of "No" is redundant.
  383. PrintReset  xPrnReset   Also could have been shortened to cPrnRst.
  384. MessageStr  cMsg        These are starting to become obvious, don't you
  385.                         think?
  386.  
  387. ======================
  388. Standard Header Format
  389. ======================
  390. Below is the recommended header format to be used for procedures/functions.
  391. This will allow the automated maintenance of library functions as well
  392. as documenting the routine.  By using this header, it will make it
  393. possible to create a routine either in dBASE or some other software that
  394. can generate a library listing, giving the pertinent information. Please
  395. also note EoF/EoP comment at the END of the function or procedure.
  396.  
  397. FUNCTION AllTrim && {ver 0.8}
  398. *--------------------------------------------------------------------------
  399. *-- Programmer..: HazMatZak
  400. *-- Date........: 07/02/1991
  401. *-- Notes.......: Used to remove leading and trailing blanks from
  402. *--               a string.
  403. *-- Written for.: dBASE IV, 1.1
  404. *-- Rev. History: 05/23/1991 0.1 - Original version (CLW)
  405. *--               06/18/1991 0.2 - Revision to modify for dHUNG
  406. *--               06/19/1991 0.3 - Revised for ...
  407. *--               06/24/1991 0.4 - Revised for ...
  408. *--               06/25/1991 0.5 - Revised again by Ken Mayer
  409. *--                                to give smaller header ...
  410. *--               etc.
  411. *-- Calls.......: None
  412. *-- Called by...: Any
  413. *-- Usage.......: AllTrim(<cArg>)
  414. *-- Example.....: ? AllTrim("  Test string  ")
  415. *-- Returns.....: String to be trimmed (i.e.:"Test string")
  416. *-- Parameters..: cArg = String to be trimmed
  417. *--------------------------------------------------------------------------
  418.        
  419.    parameters cArg
  420.  
  421. RETURN ltrim(rtrim(cArg))
  422. *-- EoF: AllTrim()
  423.  
  424. -------------
  425. Documentation
  426. -------------
  427. It is always a good idea to document code -- never assume you will be the
  428. only programmer to read your code. If it is being posted on CompuServe, a
  429. lot of people may download it. If they wish to understand what you are
  430. doing, or use just portions of your code, it is very useful to explain in
  431. at least some detail what your program/function/procedure is doing. We are
  432. not going to suggest more than attempt to make the documentation neat,
  433. concise, and to the point (don't ramble).
  434.  
  435. ----------------------
  436. dHUNG Revision History
  437. ----------------------
  438. 1991-05-23  0.1  Initial revision (clw)
  439. 1991-06-18  0.2  Revision after notations vote (clw)
  440. 1991-06-19  0.3  Memvars, Files, Fields, UDFs, Case Summary (HazMatZak)
  441. 1991-08-20  0.4  Added official header example (clw)
  442. 1991-08-26  0.5  Combined original DiFalco document (HUNG14.ZIP) with CLW's
  443.                  dHUNG documentation, and the header information
  444.                  (KenMayer).
  445. 1991-08-30  0.6  Minor corrections to make this dBASE specific (KenMayer).
  446. 1992-04-16  0.7  Minor corrections to make this 'Politically Correct'.
  447.                  (Ken Mayer (KenMayer))
  448.