home *** CD-ROM | disk | FTP | other *** search
/ Dream 52 / Amiga_Dream_52.iso / Linux / Divers / lyx-0.13.2.tar.gz / lyx-0.13.2.tar / lyx-0.13.2 / development / Code_rules / Rules < prev   
Text File  |  1998-04-23  |  4KB  |  107 lines
  1. Rules for the code in LyX
  2. -------------------------
  3.  
  4. The aim of this file is to serve as a guide for the developers, to aid us to
  5. get clean and uniform code. Still uncomplete.
  6.  
  7. In general, if you want to contribute to the main source, we expect at least 
  8. that you:
  9.  
  10. - write good C++ code: Readable, well commented and taking advantage of the 
  11.   OO model.
  12. - adapt the code to the structures already existing in LyX, or in case that 
  13.   you have better ideas, discuss them on the developer's list before writing 
  14.   the code.
  15.  
  16. These guidelines should save us a lot of work while cleaning up the code and 
  17. help us to have quality code. LyX has been haunted by problems coming from 
  18. unfinished projects by people who have left the team. Those problems will 
  19. hopefully disappear if the code is easy to hand over to somebody else.
  20.  
  21.  
  22. * Naming rules for classes
  23.  
  24.   - Use descriptive but simple and short names. For stuff specific to LyX
  25.     use LyX as prefix. Some modules, like mathed or spellchecker, could have
  26.     other prefixes.
  27.  
  28.   - Class names are usually capitalized, and function names lowercased.
  29.     Enums are in CAPS.
  30.  
  31.   - Long variables are named like thisLongVariableName.
  32.  
  33.  
  34. * Formatting
  35.  
  36.   - Please adapt the formatting of your code to the setting in LyX in that
  37.     particular file. Lars and Asger are slowly, but surely moving the source 
  38.     towards Linux kernel style formatting, aka K&R style. We suggest that you 
  39.     also do this, but this is NOT something that has been decided generally.
  40.  
  41.  
  42. * Use existing structures
  43.  
  44.   - Use LString whereever possible. LyX will someday move to Unicode, and
  45.     that will be easy if everybody uses LString now.
  46.  
  47.   - Check out the filename and path tools in filetools.h
  48.  
  49.   - Use the Error class to report errors and messages
  50.  
  51.   [add description of other existing structures]
  52.  
  53.  
  54. * Declarations
  55.   
  56.   - Use this order for the access sections of your class: public,
  57.     protected, private. The public section is interesting for every
  58.     user of the class. The private section is only of interest for the
  59.     implementors of the class (you).
  60.   
  61.   - Avoid to declare global objects in the declaration file of the class. 
  62.     If the same variable is used for all object, use a static member.
  63.  
  64.   - Avoid global or static variables. An exception to this rule is 
  65.     very private stuff like the math stack.
  66.  
  67.   - Use the const keyword like this: char const * instead of const char *
  68.     because this is more logical.
  69.  
  70.  
  71. * Documentation
  72.  
  73.   - The documentation is generated from the header files.
  74.   - You document for the other developers, not for yourself.
  75.   - You should document what the funtion do, not the implementation.
  76.   - in the .C files you document the implementation.
  77.   - Short description (///), large description (/** ... */)
  78.     (someone explain this please)
  79.   - You make the documentation by doing "make srcdoc" in the root,
  80.     and then you'll find HTML in the srcdoc/ directory. Read with
  81.     Netscape for best results.
  82.  
  83.  
  84. * NAMING RULES FOR USER-COMMANDS
  85.    
  86.   Here's the set of rules to apply when a new command name is introduced:
  87.  
  88.   1) Use the object.event order. That is, use `word-forward' instead of 
  89.      `forward-word'.
  90.   2) Don't introduce an alias for an already named object. Same for events.
  91.   3) Forward movement or focus is called `forward' (not `right').
  92.   4) Backward movement or focus is called `backward' (not `left').
  93.   5) Upward movement of focus is called `up'.
  94.   6) Downward movement is called `down'.
  95.   7) The begin of an object is called `begin' (not `start').
  96.   8) The end of an object is called `end'.
  97.  
  98.  
  99. * Using external GUI constructors (XForms fdesign)
  100.  
  101.   - Fdesign generated files should not be changed at all. The only changes
  102.     needed are gettext, compability with 0.81 or when you have made your own
  103.     xforms objects and have just a dummy in the .fd file in place of your
  104.     own. In case you have to change the generated files for any of the
  105.     reasons above, you should provide a patch against the clean generated
  106.     file. Your callbacks must be in a separate file.
  107.