home *** CD-ROM | disk | FTP | other *** search
/ Best Objectech Shareware Selections / UNTITLED.iso / boss / data / dbas / 004 / contrib.txt < prev    next >
Text File  |  1992-04-24  |  5KB  |  74 lines
  1.                         Standards of the dUFLP Library
  2.                           (written by Jay Parsons)
  3.  
  4.         The purpose of this library is to assist programmers using the dBASE 
  5. language, preferably users of the Borland dBASE products.  Contributions of 
  6. neat ways to do new things, better ways to do old things or just handy routines
  7. are earnestly requested.  Once accepted, all such routines are considered placed
  8. in the public domain, but support from the contributor will be appreciated and 
  9. may be requested.
  10.  
  11.         In order to make the library as useful as possible, please have your 
  12. contributions adhere to the following standards, which are goals more than 
  13. rules:
  14.  
  15.         Modularity - Contributions should be of procedures or functions that 
  16. can be used, as far as possible, in any context within the versions of dBASE
  17. for which written.  Where use of external global variables or files opened 
  18. before calling the routine is inevitable, the routine header should specify the
  19. required environment.
  20.  
  21.         Style - Please use the header form, styles of capitalization and naming
  22. of variables and other conventions set forth in DHUNG2.ZIP (on the BORBBS).
  23. This makes it much easier for readers of items contributed from different 
  24. sources to find the information they need; it may also be required by library-
  25. management programs to assure the inclusion of called routines in files to 
  26. which the calling routines are copied.
  27.  
  28.         Encapsulation - Routines that can reasonably operate without changing 
  29. any external variables, active windows, etc., without printing to the screen, a
  30. printer or a file and without changing any dBASE "SET" items should do so.  
  31. ALL VARIABLES CREATED WITHIN A ROUTINE SHOULD BE "PRIVATE", AND ALL PARAMETERS 
  32. LEFT UNCHANGED, to keep changes made within from affecting the outside world.  
  33. Any departures from complete encapsulation, such as opening or closing files, 
  34. input, output, changing "SET" items or work areas should be noted in the header. 
  35. This does not mean a routine should not change such items, but that if it does,
  36. it should restore them to the starting status if it reasonably can.  This 
  37. standard is necessarily subjective.  One of the nicer routines ( CURRPORT() ) in 
  38. this release is a workaround for the failure of dBASE IV 1.5 to contain a 
  39. printerset() function to report what file or device PRINTER is SET to, without 
  40. which it cannot be reset on exit.  The workaround routine is complex and slow 
  41. enough that it may be preferable simply to note in the header of a routine 
  42. using printer redirection that the routine changes the setting, leaving it to 
  43. users to add the code needed to detect the original setting and restore it if 
  44. it matters to them. 
  45.  
  46.         Error handling - There is generally no need to handle errors such as 
  47. calling a routine with the wrong number or type of parameters.  This can be 
  48. left to the calling program or dBASE itself.  Handling errors with screen 
  49. displays of messages, prompts for reentry of data, etc. is sufficiently complex
  50. that this too can usually be left to dBASE or the calling program. However, in 
  51. no case should a function return a value as an error code that might be 
  52. mistaken for a valid result, such as 0 for the average of numbers in an array 
  53. if there are no such numbers or array.  Something available to the calling 
  54. routine after the return should be provided that will, if inspected by the 
  55. calling routine, give it notice that an error has occurred.  And, of course, 
  56. the manner in which the calling routine should check for an error should be
  57. documented in the header if not obvious.
  58.  
  59.         Planning ahead - The library contains many fine routines that are 
  60. somewhat obsolete.  If contributing one for the future, try to anticipate 
  61. changes.  A center() function that takes a string of characters and prints it 
  62. in the middle of an 80 x 25 screen is nice, but one that also takes the width 
  63. and returns the string padded with blanks on the left or both ends to the given
  64. width is probably better, because it supports use with screens of other widths
  65. or heights, printing the resulting string to a file and other variations.  This
  66. too is subjective, as anticipating unlikely contingencies will require extra 
  67. and slowing code.
  68.  
  69.         This is your library.  Enjoy it, contribute what you can, and please 
  70. report any bugs or other unexpected results to:
  71.  
  72.                         Ken Mayer ( BORBBS Kenmayer)
  73.                         Programmer and Librarian
  74.