home *** CD-ROM | disk | FTP | other *** search
/ ftp.uni-stuttgart.de/pub/systems/acorn/ / Acorn.tar / Acorn / acornet / dev / basic / blib2.spk / Docs / StyleGuide < prev    next >
Text File  |  1993-03-02  |  5KB  |  140 lines
  1.  
  2. The BlibII Library Style Guide
  3. ------------------------------
  4.  
  5. Although the BlibII linker will handle several different styles for
  6. BlibII libraries, it may be helpful if the style used is consistent.
  7. Thus below is a style guide for the structure of BlibII libraries.
  8.  
  9.  
  10. The Library Introduction
  11. ------------------------
  12.  
  13. The library introduction is an important part of the library from the
  14. users point of view. It details what is contained within the library,
  15. and any information which covers the library as a whole.
  16.  
  17. This introduction should form a BlibII block of it's own (ie. should
  18. have it's own *|start and *|stop, and the block should have the same
  19. name as the library itself (or a fuller version if the name is
  20. truncated due to the limit on filename size).
  21.  
  22. Between the start and stop markers there should be the description
  23. (using BlibII description commands (*|!), and this description should
  24. follow the general description rules given below.
  25.  
  26. There should be no code part to the introduction.
  27.  
  28.  
  29. Descriptions
  30. ------------
  31.  
  32. Descriptions of both the library as a whole, and individual procedures
  33. and functions should be in a consistent format.
  34.  
  35. The first line should contain the library name (in the case of a
  36. library introduction description) or the procedure/function name and
  37. parameters required (in the case of a procedure/function).
  38.  
  39. This first line should then be followed by a single blank line
  40. (containing just the *|! command).
  41.  
  42. Each line of text should start with the BlibII command *|! and should
  43. be less than 80 characters long (including the *|!).
  44.  
  45. Extra blank lines can be included where appropriate, but there should
  46. be no blank line at the end of the description.
  47.  
  48. Descriptions should NOT contain any top bit set characters (those with
  49. ascii values above 127). This is because of a problem with most Basic
  50. editors (including Acorn's own !Edit) which causes these characters
  51. to be detokenised upon loading into the editor, but not tokenised back
  52. again upon saving.
  53.  
  54. Descriptions can contain any of the formatting commands allowed by the STW
  55. library's PROCstw_formatline. This means you can have colour changes,
  56. text left/right justification (justified to 80 chars), centralisation and
  57. tabulation (to 8 char columns). This means that if you require a '|' in
  58. your description, you should use '||'.
  59.  
  60.  
  61. BlibII blocks
  62. -------------
  63.  
  64. BlibII defines a block as starting with a '*|!start' command, and a
  65. '*|!stop' command. Although it is possible for blocks to overlap, it
  66. is not advised, and can cause problems.
  67.  
  68. A block should be formatted as follows :
  69.  
  70. The '*|start' for the block should immediately be followed by the
  71. description for that block. This description should then be followed by
  72. the body of the block (the code for the procedure(s)) and then the
  73. '*|stop' for that block.
  74.  
  75. The body of the block should contain one blank line at the end of the
  76. block, this means that extracted procedures will all have one blank
  77. line separating them in the linked program.
  78.  
  79. If the block is to be an 'update' block then the format should be :
  80.  
  81. *|start PROCprocedure
  82. *|!PROCprocedure ( param1 , param2 )
  83. *|!
  84. *|!Description of the procedure and it's parameters
  85. *|copy
  86. *|update
  87. DEFPROCprocedure(A%,B%):REM      *** update block ***
  88. .
  89. .
  90. .
  91. ENDPROC
  92.  
  93. *|copy
  94. *|downdate
  95. *|stop PROCprocedure
  96.  
  97. Every procedure in the update block should contain a 'REM' comment stating
  98. that it is in an update block. This clearly warns the user of this fact so
  99. they can avoid placing new procedures in the update block (which will be
  100. removed upon linking) or making alterations to the procedures (which will
  101. be undone upon linking).
  102.  
  103.  
  104. Procedure/Function names
  105. ------------------------
  106.  
  107. In general it is advised to make procedure/function names start with
  108. the library name (or a shorter version), for example :
  109.  
  110. PROCwimp_init     (Wimp library)
  111. PROCtemp_init     (Template library)
  112.  
  113. This is not a hard and fast rule, but care should be taken when not
  114. following this format (try to pick something that is likely to be
  115. unique, PROCf is NOT acceptable.)
  116.  
  117.  
  118. Global and Local variables
  119. --------------------------
  120.  
  121. Make sure you make all local variables LOCAL (this includes labels in
  122. assembler code which do not need to be made global, eg. loop pointers,
  123. etc.). Try to make local variables short, and if possible for integer
  124. values use A%-Z% then (if 26 not enough) a%-z%, reals a-z and A-Z,
  125. strings a$-z$ and A$-Z$. This has two advantages, speed and also it
  126. means that you don't get a mass of different symbols created just for
  127. local variables.
  128.  
  129. Global variables should start with an underscore '_' and then be
  130. followed by the library name (or variant) then another '_' then the
  131. variable name. Examples :
  132.  
  133. _wimp_buffer%    (Wimp library)
  134. _mem_error%      (Memory library)
  135.  
  136. Again this is not a hard and fast rule, but it should only be broken
  137. when there is a good reason for it (and document it).
  138.  
  139.  
  140.