|
3294
|
1 @c Copyright (C) 1996, 1997 John W. Eaton |
|
|
2 @c This is part of the Octave manual. |
|
|
3 @c For copying conditions, see the file gpl.texi. |
|
|
4 |
|
4167
|
5 @node Tips |
|
3294
|
6 @appendix Tips and Standards |
|
|
7 @cindex tips |
|
|
8 @cindex standards of coding style |
|
|
9 @cindex coding standards |
|
|
10 |
|
|
11 This chapter describes no additional features of Octave. Instead it |
|
|
12 gives advice on making effective use of the features described in the |
|
|
13 previous chapters. |
|
|
14 |
|
|
15 @menu |
|
|
16 * Style Tips:: Writing clean and robust programs. |
|
|
17 * Coding Tips:: Making code run faster. |
|
|
18 * Documentation Tips:: Writing readable documentation strings. |
|
|
19 * Comment Tips:: Conventions for writing comments. |
|
|
20 * Function Headers:: Standard headers for functions. |
|
|
21 @end menu |
|
|
22 |
|
4167
|
23 @node Style Tips |
|
3294
|
24 @section Writing Clean Octave Programs |
|
|
25 |
|
|
26 Here are some tips for avoiding common errors in writing Octave code |
|
|
27 intended for widespread use: |
|
|
28 |
|
|
29 @itemize @bullet |
|
|
30 @item |
|
|
31 Since all global variables share the same name space, and all functions |
|
|
32 share another name space, you should choose a short word to distinguish |
|
|
33 your program from other Octave programs. Then take care to begin the |
|
|
34 names of all global variables, constants, and functions with the chosen |
|
|
35 prefix. This helps avoid name conflicts. |
|
|
36 |
|
|
37 If you write a function that you think ought to be added to Octave under |
|
|
38 a certain name, such as @code{fiddle_matrix}, don't call it by that name |
|
|
39 in your program. Call it @code{mylib_fiddle_matrix} in your program, |
|
5041
|
40 and send mail to @email{maintainers@@octave.org} suggesting that it |
|
3294
|
41 be added to Octave. If and when it is, the name can be changed easily |
|
|
42 enough. |
|
|
43 |
|
|
44 If one prefix is insufficient, your package may use two or three |
|
|
45 alternative common prefixes, so long as they make sense. |
|
|
46 |
|
|
47 Separate the prefix from the rest of the symbol name with an underscore |
|
|
48 @samp{_}. This will be consistent with Octave itself and with most |
|
|
49 Octave programs. |
|
|
50 |
|
|
51 @item |
|
|
52 When you encounter an error condition, call the function @code{error} |
|
|
53 (or @code{usage}). The @code{error} and @code{usage} functions do not |
|
|
54 return. |
|
|
55 @xref{Errors}. |
|
|
56 |
|
|
57 @item |
|
|
58 Please put a copyright notice on the file if you give copies to anyone. |
|
|
59 Use the same lines that appear at the top of the function files |
|
|
60 distributed with Octave. If you have not signed papers to assign the |
|
|
61 copyright to anyone else, then place your name in the copyright notice. |
|
|
62 @end itemize |
|
|
63 |
|
4167
|
64 @node Coding Tips |
|
3294
|
65 @section Tips for Making Code Run Faster. |
|
|
66 @cindex execution speed |
|
|
67 @cindex speedups |
|
|
68 |
|
|
69 Here are some ways of improving the execution speed of Octave programs. |
|
|
70 |
|
|
71 @itemize @bullet |
|
|
72 @item |
|
|
73 Avoid looping wherever possible. |
|
|
74 |
|
|
75 @item |
|
|
76 Use iteration rather than recursion whenever possible. |
|
|
77 Function calls are slow in Octave. |
|
|
78 |
|
|
79 @item |
|
|
80 Avoid resizing matrices unnecessarily. When building a single result |
|
|
81 matrix from a series of calculations, set the size of the result matrix |
|
|
82 first, then insert values into it. Write |
|
|
83 |
|
|
84 @example |
|
|
85 @group |
|
|
86 result = zeros (big_n, big_m) |
|
|
87 for i = over:and_over |
|
|
88 r1 = @dots{} |
|
|
89 r2 = @dots{} |
|
|
90 result (r1, r2) = new_value (); |
|
|
91 endfor |
|
|
92 @end group |
|
|
93 @end example |
|
|
94 |
|
|
95 @noindent |
|
|
96 instead of |
|
|
97 |
|
|
98 @example |
|
|
99 @group |
|
|
100 result = []; |
|
|
101 for i = ever:and_ever |
|
|
102 result = [ result, new_value() ]; |
|
|
103 endfor |
|
|
104 @end group |
|
|
105 @end example |
|
|
106 |
|
|
107 @item |
|
|
108 Avoid calling @code{eval} or @code{feval} whenever possible, because |
|
|
109 they require Octave to parse input or look up the name of a function in |
|
|
110 the symbol table. |
|
|
111 |
|
|
112 If you are using @code{eval} as an exception handling mechanism and not |
|
|
113 because you need to execute some arbitrary text, use the @code{try} |
|
|
114 statement instead. @xref{The try Statement}. |
|
|
115 |
|
|
116 @item |
|
|
117 If you are calling lots of functions but none of them will need to |
|
|
118 change during your run, set the variable |
|
|
119 @code{ignore_function_time_stamp} to @code{"all"} so that Octave doesn't |
|
|
120 waste a lot of time checking to see if you have updated your function |
|
|
121 files. |
|
|
122 @end itemize |
|
|
123 |
|
4167
|
124 @node Documentation Tips |
|
3294
|
125 @section Tips for Documentation Strings |
|
|
126 |
|
|
127 Here are some tips for the writing of documentation strings. |
|
|
128 |
|
|
129 @itemize @bullet |
|
|
130 @item |
|
|
131 Every command, function, or variable intended for users to know about |
|
|
132 should have a documentation string. |
|
|
133 |
|
|
134 @item |
|
|
135 An internal variable or subroutine of an Octave program might as well have |
|
|
136 a documentation string. |
|
|
137 |
|
|
138 @item |
|
|
139 The first line of the documentation string should consist of one or two |
|
|
140 complete sentences that stand on their own as a summary. |
|
|
141 |
|
|
142 The documentation string can have additional lines that expand on the |
|
|
143 details of how to use the function or variable. The additional lines |
|
|
144 should also be made up of complete sentences. |
|
|
145 |
|
|
146 @item |
|
|
147 For consistency, phrase the verb in the first sentence of a |
|
|
148 documentation string as an infinitive with ``to'' omitted. For |
|
|
149 instance, use ``Return the frob of A and B.'' in preference to ``Returns |
|
|
150 the frob of A and B@.'' Usually it looks good to do likewise for the |
|
|
151 rest of the first paragraph. Subsequent paragraphs usually look better |
|
|
152 if they have proper subjects. |
|
|
153 |
|
|
154 @item |
|
|
155 Write documentation strings in the active voice, not the passive, and in |
|
|
156 the present tense, not the future. For instance, use ``Return a list |
|
|
157 containing A and B.'' instead of ``A list containing A and B will be |
|
|
158 returned.'' |
|
|
159 |
|
|
160 @item |
|
|
161 Avoid using the word ``cause'' (or its equivalents) unnecessarily. |
|
|
162 Instead of, ``Cause Octave to display text in boldface,'' write just |
|
|
163 ``Display text in boldface.'' |
|
|
164 |
|
|
165 @item |
|
|
166 Do not start or end a documentation string with whitespace. |
|
|
167 |
|
|
168 @item |
|
|
169 Format the documentation string so that it fits in an Emacs window on an |
|
|
170 80-column screen. It is a good idea for most lines to be no wider than |
|
|
171 60 characters. |
|
|
172 |
|
|
173 However, rather than simply filling the entire documentation string, you |
|
|
174 can make it much more readable by choosing line breaks with care. |
|
|
175 Use blank lines between topics if the documentation string is long. |
|
|
176 |
|
|
177 @item |
|
|
178 @strong{Do not} indent subsequent lines of a documentation string so |
|
|
179 that the text is lined up in the source code with the text of the first |
|
|
180 line. This looks nice in the source code, but looks bizarre when users |
|
|
181 view the documentation. Remember that the indentation before the |
|
|
182 starting double-quote is not part of the string! |
|
|
183 |
|
|
184 @item |
|
|
185 The documentation string for a variable that is a yes-or-no flag should |
|
|
186 start with words such as ``Nonzero means@dots{}'', to make it clear that |
|
|
187 all nonzero values are equivalent and indicate explicitly what zero and |
|
|
188 nonzero mean. |
|
|
189 |
|
|
190 @item |
|
|
191 When a function's documentation string mentions the value of an argument |
|
|
192 of the function, use the argument name in capital letters as if it were |
|
|
193 a name for that value. Thus, the documentation string of the operator |
|
|
194 @code{/} refers to its second argument as @samp{DIVISOR}, because the |
|
|
195 actual argument name is @code{divisor}. |
|
|
196 |
|
|
197 Also use all caps for meta-syntactic variables, such as when you show |
|
|
198 the decomposition of a list or vector into subunits, some of which may |
|
|
199 vary. |
|
|
200 @end itemize |
|
|
201 |
|
4167
|
202 @node Comment Tips |
|
3294
|
203 @section Tips on Writing Comments |
|
|
204 |
|
|
205 Here are the conventions to follow when writing comments. |
|
|
206 |
|
|
207 @table @samp |
|
|
208 @item # |
|
|
209 Comments that start with a single sharp-sign, @samp{#}, should all be |
|
|
210 aligned to the same column on the right of the source code. Such |
|
|
211 comments usually explain how the code on the same line does its job. In |
|
|
212 the Emacs mode for Octave, the @kbd{M-;} (@code{indent-for-comment}) |
|
|
213 command automatically inserts such a @samp{#} in the right place, or |
|
|
214 aligns such a comment if it is already present. |
|
|
215 |
|
|
216 @item ## |
|
|
217 Comments that start with two semicolons, @samp{##}, should be aligned to |
|
|
218 the same level of indentation as the code. Such comments usually |
|
|
219 describe the purpose of the following lines or the state of the program |
|
|
220 at that point. |
|
|
221 @end table |
|
|
222 |
|
|
223 @noindent |
|
|
224 The indentation commands of the Octave mode in Emacs, such as @kbd{M-;} |
|
|
225 (@code{indent-for-comment}) and @kbd{TAB} (@code{octave-indent-line}) |
|
|
226 automatically indent comments according to these conventions, |
|
|
227 depending on the number of semicolons. @xref{Comments,, |
|
|
228 Manipulating Comments, emacs, The GNU Emacs Manual}. |
|
|
229 |
|
4167
|
230 @node Function Headers |
|
3294
|
231 @section Conventional Headers for Octave Functions |
|
|
232 @cindex header comments |
|
|
233 |
|
|
234 Octave has conventions for using special comments in function files |
|
|
235 to give information such as who wrote them. This section explains these |
|
|
236 conventions. |
|
|
237 |
|
|
238 The top of the file should contain a copyright notice, followed by a |
|
|
239 block of comments that can be used as the help text for the function. |
|
|
240 Here is an example: |
|
|
241 |
|
|
242 @example |
|
|
243 ## Copyright (C) 1996, 1997 John W. Eaton |
|
|
244 ## |
|
|
245 ## This file is part of Octave. |
|
|
246 ## |
|
|
247 ## Octave is free software; you can redistribute it and/or |
|
|
248 ## modify it under the terms of the GNU General Public |
|
|
249 ## License as published by the Free Software Foundation; |
|
|
250 ## either version 2, or (at your option) any later version. |
|
|
251 ## |
|
|
252 ## Octave is distributed in the hope that it will be useful, |
|
|
253 ## but WITHOUT ANY WARRANTY; without even the implied |
|
|
254 ## warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR |
|
|
255 ## PURPOSE. See the GNU General Public License for more |
|
|
256 ## details. |
|
|
257 ## |
|
|
258 ## You should have received a copy of the GNU General Public |
|
|
259 ## License along with Octave; see the file COPYING. If not, |
|
5307
|
260 ## write to the Free Software Foundation, Inc., 51 Franklin Street, |
|
|
261 ## Fifth Floor, Boston, MA 02110-1301, USA. |
|
3294
|
262 |
|
|
263 ## usage: [IN, OUT, PID] = popen2 (COMMAND, ARGS) |
|
|
264 ## |
|
|
265 ## Start a subprocess with two-way communication. COMMAND |
|
|
266 ## specifies the name of the command to start. ARGS is an |
|
|
267 ## array of strings containing options for COMMAND. IN and |
|
|
268 ## OUT are the file ids of the input and streams for the |
|
|
269 ## subprocess, and PID is the process id of the subprocess, |
|
|
270 ## or -1 if COMMAND could not be executed. |
|
|
271 ## |
|
|
272 ## Example: |
|
|
273 ## |
|
|
274 ## [in, out, pid] = popen2 ("sort", "-nr"); |
|
|
275 ## fputs (in, "these\nare\nsome\nstrings\n"); |
|
|
276 ## fclose (in); |
|
|
277 ## while (isstr (s = fgets (out))) |
|
|
278 ## fputs (stdout, s); |
|
|
279 ## endwhile |
|
|
280 ## fclose (out); |
|
|
281 @end example |
|
|
282 |
|
|
283 Octave uses the first block of comments in a function file that do not |
|
|
284 appear to be a copyright notice as the help text for the file. For |
|
|
285 Octave to recognize the first comment block as a copyright notice, it |
|
|
286 must match the regular expression |
|
|
287 |
|
|
288 @example |
|
|
289 ^ Copyright (C).*\n\n This file is part of Octave. |
|
|
290 @end example |
|
|
291 |
|
|
292 @noindent |
|
|
293 or |
|
|
294 |
|
|
295 @example |
|
|
296 ^ Copyright (C).*\n\n This program is free softwar |
|
|
297 @end example |
|
|
298 |
|
|
299 @noindent |
|
|
300 (after stripping the leading comment characters). This is a fairly |
|
|
301 strict requirement, and may be relaxed somewhat in the future. |
|
|
302 |
|
|
303 After the copyright notice and help text come several @dfn{header |
|
|
304 comment} lines, each beginning with @samp{## @var{header-name}:}. For |
|
|
305 example, |
|
|
306 |
|
|
307 @example |
|
|
308 @group |
|
|
309 ## Author: jwe |
|
|
310 ## Keywords: subprocesses input-output |
|
|
311 ## Maintainer: jwe |
|
|
312 @end group |
|
|
313 @end example |
|
|
314 |
|
|
315 Here is a table of the conventional possibilities for @var{header-name}: |
|
|
316 |
|
|
317 @table @samp |
|
|
318 @item Author |
|
|
319 This line states the name and net address of at least the principal |
|
|
320 author of the library. |
|
|
321 |
|
|
322 @smallexample |
|
|
323 ## Author: John W. Eaton <jwe@@bevo.che.wisc.edu> |
|
|
324 @end smallexample |
|
|
325 |
|
|
326 @item Maintainer |
|
|
327 This line should contain a single name/address as in the Author line, or |
|
|
328 an address only, or the string @samp{jwe}. If there is no maintainer |
|
|
329 line, the person(s) in the Author field are presumed to be the |
|
|
330 maintainers. The example above is mildly bogus because the maintainer |
|
|
331 line is redundant. |
|
|
332 |
|
|
333 The idea behind the @samp{Author} and @samp{Maintainer} lines is to make |
|
|
334 possible a function to ``send mail to the maintainer'' without |
|
|
335 having to mine the name out by hand. |
|
|
336 |
|
|
337 Be sure to surround the network address with @samp{<@dots{}>} if |
|
|
338 you include the person's full name as well as the network address. |
|
|
339 |
|
|
340 @item Created |
|
|
341 This optional line gives the original creation date of the |
|
|
342 file. For historical interest only. |
|
|
343 |
|
|
344 @item Version |
|
|
345 If you wish to record version numbers for the individual Octave program, |
|
|
346 put them in this line. |
|
|
347 |
|
|
348 @item Adapted-By |
|
|
349 In this header line, place the name of the person who adapted the |
|
|
350 library for installation (to make it fit the style conventions, for |
|
|
351 example). |
|
|
352 |
|
|
353 @item Keywords |
|
|
354 This line lists keywords. Eventually, it will be used by an apropos |
|
|
355 command to allow people will find your package when they're looking for |
|
|
356 things by topic area. To separate the keywords, you can use spaces, |
|
|
357 commas, or both. |
|
|
358 @end table |
|
|
359 |
|
|
360 Just about every Octave function ought to have the @samp{Author} and |
|
|
361 @samp{Keywords} header comment lines. Use the others if they are |
|
|
362 appropriate. You can also put in header lines with other header |
|
|
363 names---they have no standard meanings, so they can't do any harm. |
