home *** CD-ROM | disk | FTP | other *** search
/ vim.ftp.fu-berlin.de / 2015-02-03.vim.ftp.fu-berlin.de.tar / vim.ftp.fu-berlin.de / mac / vim55rt.sit / runtime / doc / develop.txt < prev    next >
Encoding:
Text File  |  1999-09-25  |  10.2 KB  |  306 lines  |  [TEXT/MPS ]
  1. *develop.txt*   For Vim version 5.5.  Last change: 1999 Sep 18
  2.  
  3.  
  4.           VIM REFERENCE MANUAL    by Bram Moolenaar
  5.  
  6.  
  7. Development of Vim.                    *development*
  8.  
  9. This text is important for those who want to be involved in further developing
  10. Vim.
  11.  
  12. 1. Design goals        |design-goals|
  13. 2. Coding style        |coding-style|
  14.  
  15. ==============================================================================
  16. 1. Design goals                        *design-goals*
  17.  
  18. Most important things come first (roughly).
  19.  
  20. Note that quite a few items are contradicting.  This is intentional.  A
  21. balance must be found between them.
  22.  
  23.  
  24. VIM IS... VI COMPATIBLE                    *design-compatible*
  25.  
  26. First of all, it should be possible to use Vim as a drop-in replacement for
  27. Vi.  When the user wants to, he can use Vim in compatible mode and hardly
  28. notice any difference with the original Vi.
  29.  
  30. Exceptions:
  31. - We don't reproduce obvious Vi bugs in Vim.
  32. - There are different versions of Vi.  I am using Version 3.7 (6/7/85) as a
  33.   reference.  But support for other versions is also included when possible.
  34.   The Vi part of POSIX is not considered a definitive source.
  35. - Vim adds new commands, you cannot rely on some command to fail because it
  36.   didn't exist in Vi.
  37. - Vim will have a lot of features that Vi doesn't have.  Going back from Vim
  38.   to Vi will be a problem, this cannot be avoided.
  39. - Some things are hardly ever used (open mode, sending an e-mail when
  40.   crashing, etc.).  Those will only be included when someone has a good reason
  41.   why it should be included and it's not too much work.
  42. - For some items it is discutable whether Vi compatibility should be
  43.   maintained.  There will be an option flag for these.
  44.  
  45.  
  46. VIM IS... IMPROVED                    *design-improved*
  47.  
  48. The IMproved bits of Vim should make it a better Vi, without becoming a
  49. completely different editor.  Extensions are done with a "Vi spirit".
  50. - Use the keyboard as much as feasible.  The mouse requires a third hand,
  51.   which we don't have.  Many terminals don't have a mouse.
  52. - When the mouse is used anyway, avoid the need to switch back to the
  53.   keyboard.  Avoid mixing mouse and keyboard handling.
  54. - Add commands and options in a consistent way.  Otherwise people will have a
  55.   hard time finding and remembering them.  Keep in mind that more commands and
  56.   options will be added later.
  57. - A feature that people do not know about is a useless feature.  Don't add
  58.   obscure features, or at least add hints in documentation that they exists.
  59. - Minimize using CTRL and other modifiers, they are more difficult to type.
  60. - There are many first-time and unexperienced Vim users.  Make it easy for
  61.   them to start using Vim and learn more over time.
  62. - There is no limit to the features that can be added.  Selecting new features
  63.   is one based on (1) what users ask for, (2) how much effort it takes to
  64.   implement and (3) someone actually implementing it.
  65.  
  66.  
  67. VIM IS... MULTI PLATFORM                *design-multi-platform*
  68.  
  69. Vim tries to help as many users on as many platforms as possible.
  70. - Support many kinds of terminals.  The minimal demands are cursor positioning
  71.   and clear-screen.  Commands should only use key strokes that most keyboards
  72.   have.  Support all the keys on the keyboard for mapping.
  73. - Support many platforms.  A condition is that there is someone willing to do
  74.   Vim development on that platform, and it doesn't mean messing up the code.
  75. - Support many compilers and libraries.  Not everybody is able or allowed to
  76.   install another compiler or GUI library.
  77. - People switch from one platform to another, and from GUI to terminal
  78.   version.  Features should be present in all versions, or at least in as many
  79.   as possible with a reasonable effort.  Try to avoid that users must switch
  80.   between platforms to accomplish their work efficiently.
  81. - That a feature is not possible on some platforms, or only possible on one
  82.   platform, does not mean it cannot be implemented.  [This intentionally
  83.   contradicts the previous item, these two must be balanced.]
  84.  
  85.  
  86. VIM IS... WELL DOCUMENTED                *design-documented*
  87.  
  88. - A feature that isn't documented is a useless feature.  A patch for a new
  89.   feature must include the documentation.
  90. - Documentation should be comprehensive and understandable.  Using examples is
  91.   recommended.
  92. - Don't make the text unneccesarily long.  Less documentation means that an
  93.   item is easier to find.
  94.  
  95.  
  96. VIM IS... HIGH SPEED AND SMALL IN SIZE            *design-speed-size*
  97.  
  98. Using Vim must not be a big attack on system resources.  Keep it small and
  99. fast.
  100. - Computers are becoming faster and bigger each year.  Vim can grow too, but
  101.   no faster than computers are growing.  Keep Vim usable on older systems.
  102. - Many users start Vim from a shell very often.  Startup time must be short.
  103. - Commands must work efficient.  The time they consume must be as small as
  104.   possible.  Useful commands may take longer.
  105. - Don't forget that some people use Vim over a slow connection.  Minimize the
  106.   communication overhead.
  107. - Items that add considerably to the size and are not used by many people
  108.   should be a feature that can be disabled.
  109. - Vim is a component among other components.  Don't turn it into a massive
  110.   application, but have it work well together with other programs.
  111.  
  112.  
  113. VIM IS... MAINTAINABLE                    *design-maintain*
  114.  
  115. - The source code should not become a mess.  It should be reliable code.
  116. - Use the same layout in all files to make it easy to read |coding-style|.
  117. - Use comments in a useful way!
  118. - Porting to another platform should be made easy, without having to change
  119.   too much platform-independent code.
  120. - Use the object-oriented spirit: Put data and code together.  Minimize the
  121.   knowledge spread to other parts of the code.
  122.  
  123.  
  124. VIM IS... NOT                        *design-not*
  125.  
  126. - Vim is not a shell or an Operating System.  You will not be able to run a
  127.   shell inside Vim or use it to control a debugger.  This should work the
  128.   other way around: Use Vim as a component from a shell or in an IDE.
  129. - Vim is not a fancy GUI editor that tries to look nice at the cost of
  130.   being less consistent over all platforms.  But functional GUI features are
  131.   welcomed.
  132.  
  133. ==============================================================================
  134. 2. Coding style                        *coding-style*
  135.  
  136. These are the rules to use when making changes to the Vim source code.  Please
  137. stick to these rules, to keep the sources readable and maintainable.
  138.  
  139. This list is not complete.  Look in the source code for more examples.
  140.  
  141.  
  142. MAKING CHANGES                        *style-changes*
  143.  
  144. The basic steps to make changes to the code:
  145. 1. Adjust the documentation.  Doing this first gives you an impression of how
  146.    your changes affect the user.
  147. 2. Make the source code changes.
  148. 3. Check ../doc/todo.txt if the change affects any listed item.
  149. 4. Make a patch with "diff -c" against the unmodified code and docs.
  150. 5. Make a note about what changed and include it with the patch.
  151.  
  152.  
  153. USE OF COMMON FUNCTIONS                    *style-functions*
  154.  
  155. Some functions that are common to use, have a special Vim version.  Always
  156. consider using the Vim version, because they were introduced with a reason.
  157.  
  158. NORMAL NAME    VIM NAME    DIFFERENCE OF VIM VERSION
  159. free()        vim_free()    Checks for freeing NULL
  160. malloc()    alloc()        Checks for out of memory situation
  161. malloc()    lalloc()    Like alloc(), but has long argument
  162. strcpy()    STRCPY()    Includes cast to (char *), for char_u * args
  163. strchr()    vim_strchr()    Accepts special characters
  164. strrchr()    vim_strrchr()    Accepts special characters
  165. isspace()    vim_isspace()    Can handle characters > 128
  166. iswhite()    vim_iswhite()    Only TRUE for Tab and space
  167. memcpy()    vim_memmove()    Handles overlapped copies
  168. bcopy()        vim_memmove()    Handles overlapped copies
  169. memset()    vim_memset()    Uniform for all systems
  170.  
  171.  
  172. NAMES                            *style-names*
  173.  
  174. Because of the requirement that Vim runs on as many systems as possible, we
  175. need to avoid using names that are already defined by the system.  This is a
  176. list of names that are known to cause trouble.  The name is given as a regexp
  177. pattern.
  178.  
  179. is.*()        POSIX, ctype.h
  180. to.*()        POSIX, ctype.h
  181.  
  182. d_.*        POSIX, dirent.h
  183. l_.*        POSIX, fcntl.h
  184. gr_.*        POSIX, grp.h
  185. pw_.*        POSIX, pwd.h
  186. sa_.*        POSIX, signal.h
  187. mem.*        POSIX, string.h
  188. str.*        POSIX, string.h
  189. wcs.*        POSIX, string.h
  190. st_.*        POSIX, stat.h
  191. tms_.*        POSIX, times.h
  192. tm_.*        POSIX, time.h
  193. c_.*        POSIX, termios.h
  194. MAX.*        POSIX, limits.h
  195. __.*        POSIX, system
  196. _[A-Z].*    POSIX, system
  197. E[A-Z0-9]*    POSIX, errno.h
  198.  
  199. wait        don't use as argument to a function, conflicts with types.h
  200. index        shadows global declaration
  201. time        shadows global declaration
  202. new        C++ reserved keyword
  203. try        Borland C++ doesn't like it to be used as a variable.
  204.  
  205. basename()    GNU string function
  206. dirname()    GNU string function
  207. get_env_value()    Linux system function
  208.  
  209.  
  210. VARIOUS                            *style-various*
  211.  
  212. Don't use '\"', some compilers can't handle it.  '"' works fine.
  213.  
  214. Don't use:
  215.     #if HAVE_SOME
  216. Some compilers can't handle that and complain that "HAVE_SOME" is not defined.
  217. Use
  218.     #ifdef HAVE_SOME
  219. or
  220.     #if defined(HAVE_SOME)
  221.  
  222.  
  223. STYLE                            *style-examples*
  224.  
  225. General rule: One statement per line.
  226.  
  227. Wrong:        if (cond) a = 1;
  228.  
  229. OK:        if (cond)
  230.         a = 1;
  231.  
  232. Wrong:        while (cond);
  233.  
  234. OK:        while (cond)
  235.         ;
  236.  
  237. Wrong:        do a = 1; while (cond);
  238.  
  239. OK:        do
  240.         a = 1;
  241.         while (cond);
  242.  
  243.  
  244. Functions start with:
  245.  
  246. Wrong:    int function_name(int arg1, int arg2)
  247.  
  248. OK:    /*
  249.      * Explanation of what this function is used for.
  250.      *
  251.      * Return value explanation.
  252.      */
  253.         int
  254.     function_name(arg1, arg2)
  255.         int        arg1;        /* short comment about arg1 */
  256.         int        arg2;        /* short comment about arg2 */
  257.     {
  258.         int        local;        /* comment about local */
  259.  
  260.         local = arg1 * arg2;
  261.  
  262. NOTE: Don't use ANSI style function declarations.  A few people still have to
  263. use a compiler that doesn't support it.
  264.  
  265.  
  266. SPACES AND PUNCTUATION                    *style-spaces*
  267.  
  268. No space between a function name and the bracket:
  269.  
  270. Wrong:  func (arg);
  271. OK:    func(arg);
  272.  
  273. Do use a space after if, while, switch, etc.
  274.  
  275. Wrong:    if(arg)        for(;;)
  276. OK:    if (arg)    for (;;)
  277.  
  278. Use a space after a comma and semicolon:
  279.  
  280. Wrong:  func(arg1,arg2);    for (i = 0;i < 2;++i)
  281. OK:    func(arg1, arg2);    for (i = 0; i < 2; ++i)
  282.  
  283. Use a space before and after '=', '+', '/', etc.
  284.  
  285. Wrong:    var=a*5;
  286. OK:    var = a * 5;
  287.  
  288. In general: Use empty lines to group lines of code together.  Put a comment
  289. just above the group of lines.  This makes it more easy to quickly see what is
  290. being done.
  291.  
  292. OK:    /* Prepare for building the table. */
  293.     get_first_item();
  294.     table_idx = 0;
  295.  
  296.     /* Build the table */
  297.     while (has_item())
  298.         table[table_idx++] = next_item();
  299.  
  300.     /* Finish up. */
  301.     cleanup_items();
  302.     generate_hash(table);
  303.  
  304.  
  305.  vim:tw=78:ts=8:sw=8:
  306.