| blob | fd2569162bf5fa4057143735810820019b905ab0 |
1 *develop.txt* For Vim version 5.8. Last change: 2000 Apr 13
4 VIM REFERENCE MANUAL by Bram Moolenaar
7 Development of Vim. *development*
9 This text is important for those who want to be involved in further developing
10 Vim.
12 1. Design goals |design-goals|
13 2. Coding style |coding-style|
15 ==============================================================================
16 1. Design goals *design-goals*
18 Most important things come first (roughly).
20 Note that quite a few items are contradicting. This is intentional. A
21 balance must be found between them.
24 VIM IS... VI COMPATIBLE *design-compatible*
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.
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 debatable whether Vi compatibility should be
43 maintained. There will be an option flag for these.
46 VIM IS... IMPROVED *design-improved*
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 inexperienced 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.
67 VIM IS... MULTI PLATFORM *design-multi-platform*
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.]
86 VIM IS... WELL DOCUMENTED *design-documented*
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 unnecessarily long. Less documentation means that an
93 item is easier to find.
96 VIM IS... HIGH SPEED AND SMALL IN SIZE *design-speed-size*
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.
113 VIM IS... MAINTAINABLE *design-maintain*
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.
124 VIM IS... FLEXIBLE *design-flexible*
126 Vim should make it easy for users to work in their preferred styles rather
127 than coercing its users into particular patterns of work. This can be for
128 items with a large impact (e.g., the 'compatible' option) or for details. The
129 defaults are carefully chosen such that most users will enjoy using Vim as it
130 is. Commands and options can be used to adjust Vim to the desire of the user
131 and its environment.
134 VIM IS... NOT *design-not*
136 - Vim is not a shell or an Operating System. You will not be able to run a
137 shell inside Vim or use it to control a debugger. This should work the
138 other way around: Use Vim as a component from a shell or in an IDE.
139 A satirical way to say this: "Unlike Emacs, Vim does not attempt to include
140 everything but the kitchen sink, but some people say that you can clean one
141 with it. ;-)"
142 - Vim is not a fancy GUI editor that tries to look nice at the cost of
143 being less consistent over all platforms. But functional GUI features are
144 welcomed.
146 ==============================================================================
147 2. Coding style *coding-style*
149 These are the rules to use when making changes to the Vim source code. Please
150 stick to these rules, to keep the sources readable and maintainable.
152 This list is not complete. Look in the source code for more examples.
155 MAKING CHANGES *style-changes*
157 The basic steps to make changes to the code:
158 1. Adjust the documentation. Doing this first gives you an impression of how
159 your changes affect the user.
160 2. Make the source code changes.
161 3. Check ../doc/todo.txt if the change affects any listed item.
162 4. Make a patch with "diff -c" against the unmodified code and docs.
163 5. Make a note about what changed and include it with the patch.
166 USE OF COMMON FUNCTIONS *style-functions*
168 Some functions that are common to use, have a special Vim version. Always
169 consider using the Vim version, because they were introduced with a reason.
171 NORMAL NAME VIM NAME DIFFERENCE OF VIM VERSION
172 free() vim_free() Checks for freeing NULL
173 malloc() alloc() Checks for out of memory situation
174 malloc() lalloc() Like alloc(), but has long argument
175 strcpy() STRCPY() Includes cast to (char *), for char_u * args
176 strchr() vim_strchr() Accepts special characters
177 strrchr() vim_strrchr() Accepts special characters
178 isspace() vim_isspace() Can handle characters > 128
179 iswhite() vim_iswhite() Only TRUE for Tab and space
180 memcpy() vim_memmove() Handles overlapped copies
181 bcopy() vim_memmove() Handles overlapped copies
182 memset() vim_memset() Uniform for all systems
185 NAMES *style-names*
187 Because of the requirement that Vim runs on as many systems as possible, we
188 need to avoid using names that are already defined by the system. This is a
189 list of names that are known to cause trouble. The name is given as a regexp
190 pattern.
192 is.*() POSIX, ctype.h
193 to.*() POSIX, ctype.h
195 d_.* POSIX, dirent.h
196 l_.* POSIX, fcntl.h
197 gr_.* POSIX, grp.h
198 pw_.* POSIX, pwd.h
199 sa_.* POSIX, signal.h
200 mem.* POSIX, string.h
201 str.* POSIX, string.h
202 wcs.* POSIX, string.h
203 st_.* POSIX, stat.h
204 tms_.* POSIX, times.h
205 tm_.* POSIX, time.h
206 c_.* POSIX, termios.h
207 MAX.* POSIX, limits.h
208 __.* POSIX, system
209 _[A-Z].* POSIX, system
210 E[A-Z0-9]* POSIX, errno.h
212 wait don't use as argument to a function, conflicts with types.h
213 index shadows global declaration
214 time shadows global declaration
215 new C++ reserved keyword
216 try Borland C++ doesn't like it to be used as a variable.
218 basename() GNU string function
219 dirname() GNU string function
220 get_env_value() Linux system function
223 VARIOUS *style-various*
225 Don't use '\"', some compilers can't handle it. '"' works fine.
227 Don't use:
228 #if HAVE_SOME
229 Some compilers can't handle that and complain that "HAVE_SOME" is not defined.
230 Use
231 #ifdef HAVE_SOME
232 or
233 #if defined(HAVE_SOME)
236 STYLE *style-examples*
238 General rule: One statement per line.
240 Wrong: if (cond) a = 1;
242 OK: if (cond)
243 a = 1;
245 Wrong: while (cond);
247 OK: while (cond)
248 ;
250 Wrong: do a = 1; while (cond);
252 OK: do
253 a = 1;
254 while (cond);
257 Functions start with:
259 Wrong: int function_name(int arg1, int arg2)
261 OK: /*
262 * Explanation of what this function is used for.
263 *
264 * Return value explanation.
265 */
266 int
267 function_name(arg1, arg2)
268 int arg1; /* short comment about arg1 */
269 int arg2; /* short comment about arg2 */
270 {
271 int local; /* comment about local */
273 local = arg1 * arg2;
275 NOTE: Don't use ANSI style function declarations. A few people still have to
276 use a compiler that doesn't support it.
279 SPACES AND PUNCTUATION *style-spaces*
281 No space between a function name and the bracket:
283 Wrong: func (arg);
284 OK: func(arg);
286 Do use a space after if, while, switch, etc.
288 Wrong: if(arg) for(;;)
289 OK: if (arg) for (;;)
291 Use a space after a comma and semicolon:
293 Wrong: func(arg1,arg2); for (i = 0;i < 2;++i)
294 OK: func(arg1, arg2); for (i = 0; i < 2; ++i)
296 Use a space before and after '=', '+', '/', etc.
298 Wrong: var=a*5;
299 OK: var = a * 5;
301 In general: Use empty lines to group lines of code together. Put a comment
302 just above the group of lines. This makes it more easy to quickly see what is
303 being done.
305 OK: /* Prepare for building the table. */
306 get_first_item();
307 table_idx = 0;
309 /* Build the table */
310 while (has_item())
311 table[table_idx++] = next_item();
313 /* Finish up. */
314 cleanup_items();
315 generate_hash(table);
318 vim:tw=78:ts=8:sw=8: