home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 1 / RISC_DISC_1.iso / pd_share / code / desklib / Docs / QuickRefs / BriefGuide next >
Encoding:
Text File  |  1993-05-13  |  5.4 KB  |  99 lines
  1. Brief style guide
  2. =================
  3.  
  4. This is a style guide for any code you submit to DeskLib. It is not
  5. a compulsory style, but it makes it easier to swap between your code
  6. and DeskLib code without confusion, and also makes life much easier
  7. for me if you decide to submit your code to me at any stage.
  8.  
  9. You can use any style you like for your internal code, but please try to
  10. stick to the following guidelines for external interface data structures and
  11. function calls. (Note that it is also preferable that the internal code and
  12. data structures follow these rules, to ensure you don't mistakenly use
  13. "internal" styles on "external" structures, and to make the code more
  14. readable for other people)
  15.  
  16. #includes:            #include "DeskLib:Header.h"
  17.                       Always use the DeskLib: in the name, as some DeskLib
  18.                       header names will clash with RISC OS Lib and ANSI names.
  19. Function names:       Wimp_OpenWindow
  20. Type names:           window_openblock, mouse_block
  21. Global variables:     message_globaldata (use *sparingly*!)
  22. 'Internal' variables: message__notglobal
  23.                       (These are declared as global variables so that several
  24.                       library files can access them, however, they are only
  25.                       intended for use in that sublibrary, and the user should
  26.                       ignore their existence!)
  27. Variable names:       window, icondata
  28. Constants:            icon_SELECTED, window_MOVEABLE
  29.  
  30. Spelling:             Try to use the spelling used from this priority list:
  31.                         a) Elsewhere in DeskLib
  32.                         b) In the Programmers reference manuals
  33.                         c) In a dictionary ;-)
  34.                       -The only bad spelling problem I have noticed in RISC OS
  35.                        Lib is Writeable vs. Writable. (They use BOTH!)
  36.                        DeskLib uses the latter.
  37.     
  38. Name-choice:          Each word should be abbreviated to 4-6 characters
  39.                       Entire names should not be more than about 24 characters
  40.                       Use Acorn's RISC OS Lib name if it is reasonable and
  41.                        fits the guidelines - this makes switching between the
  42.                        libraries easier.
  43.                       Try to make the name as meaningful as possible
  44.                       ALWAYS use the same name for the same thing
  45.                       (e.g. a scroll position is ALWAYS a scroll.x/scroll.y)
  46.     
  47. Structures:           Where a portion of a structure is used elsewhere, think
  48.                       about making it a seperate structure definition
  49.                       e.g. a rectangle is made up of 2 x,y coordinate pairs,
  50.                       so it is logical (and useful) to define an x,y pair as a
  51.                       point, and a rectangle as being constructed from two
  52.                       such points.
  53.     
  54.     
  55. Code formatting:      Anything goes so long as it is tidy and readable.
  56.                       Preferably format code so it will fit into a 79-column
  57.                       display.
  58.     
  59. Code file naming:     Try to use the group name that is used in the module.
  60.                       e.g. all Icon_XXX code should go into a file icon.c,
  61.                       or make up several .c files in a sublibrary 'Icon'.
  62.                       
  63.     
  64. Header files:         Preferably use two files for each module: one to define
  65.                       anything internal to the code file ("icondefs.h"), and
  66.                       one to define the external interface (function prototypes
  67.                       and external variable types ("icon.h"). If making
  68.                       sublibraries, then the 'internal definition' header can
  69.                       go into the sublib directory's .h, while the external
  70.                       interface header should go in the main DeskLib headers
  71.                       directory.
  72.     
  73.                       Try to put a comment with each function prototype and
  74.                       type definition in your "icon.h" header file, describing
  75.                       the functions useage.
  76.                       I prefer to leave the variable names in my function
  77.                       prototypes, as this also gives a good clue as to what
  78.                       you should pass in to the function (not to mention saving
  79.                       you the bother of deleting the names when you copy/paste)
  80.     
  81.                       Guard against your header file being included more than
  82.                       once with #define __dl_<name>_h.
  83.                       Please define this macro, even if you don't need to worry
  84.                       about multiple inclusion: It is a useful way to know if
  85.                       your .h file has been looked at by the compiler.
  86.  
  87.                       Note that "#pragma include_only_once" is out, as it is
  88.                       a compiler-dependant feature.
  89.     
  90. Other docs:           Any other documentation files detailing internal and
  91.                       external data structures, and manual entries for
  92.                       functions would be most welcome. (Please copy the format
  93.                       of any similar files you may find in the DeskLib release
  94.                       where possible).
  95.     
  96.                       I guess if I'm going to one day make an Impression
  97.                       version of the Docs up, it would be preferable if you
  98.                       don't indent stuff like I have done in this file!
  99.