Skip to content
This repository
Newer
Older
100644 931 lines (623 sloc) 29.444 kb
fba2bc19 » coke
2010-04-14 PDD cleanup (TT #1536); Remove maintainer, changes sections.
1 # Copyright (C) 2001-2010, Parrot Foundation.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
2
740e7748 » allisonrandal
2009-03-09 [cage] Cleaning up the PDD titles for better display and
3 =head1 PDD 7: Conventions and Guidelines for Parrot Source Code
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
4
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
5 =head2 Abstract
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
6
7 This document describes the various rules, guidelines and advice for those
8 wishing to contribute to the source code of Parrot, in such areas as code
9 structure, naming conventions, comments etc.
10
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
11 =head2 Synopsis
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
12
13 Not applicable.
14
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
15 =head2 Description
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
16
17 One of the criticisms of Perl 5 is that its source code is impenetrable to
18 newcomers, due to such things as inconsistent or obscure variable naming
19 conventions, lack of comments in the source code, and so on. We don't intend
20 to make the same mistake when writing Parrot. Hence this document.
21
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
22 We define three classes of conventions:
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
23
24 =over 4
25
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
26 =item I<"must">
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
27
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
28 Items labelled I<must> are mandatory; and code will not be accepted (apart
29 from in exceptional circumstances) unless it obeys them.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
30
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
31 =item I<"should">
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
32
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
33 Items labelled I<should> are strong guidelines that should normally be
34 followed unless there is a sensible reason to do otherwise.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
35
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
36 =item I<"may">
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
37
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
38 Items labelled I<may> are tentative suggestions to be used at your discretion.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
39
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
40 =back
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
41
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
42 Note that since Parrot is substantially implemented in C, these rules apply to
43 C language source code unless otherwise specified.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
44
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
45 =head2 Implementation
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
46
47
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
48 =head3 Language Standards and Portability
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
49
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
50 =over 4
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
51
691c8920 » chipdude
2006-09-05 Move pdd07 out of clip
52 =item *
53
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
54 C code must generally depend on only those language and library features
55 specified by the ISO C89 standard.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
56
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
57 In addition, C code may assume that any pointer value can be coerced to an
58 integral type (no smaller than typedef C<INTVAL> in Parrot), then back to its
59 original type, without loss.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
60
0899792a » chromatic
2007-06-06 [GC] Use more mem_sys_*_zeroed (Mehmet Yavuz Selim Soyturk).
61 Also C code may assume that there is a single NULL pointer representation
62 and that it consists of a number, usually 4 or 8, of '\0' chars in memory.
63
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
64 C code that makes assumptions beyond these must depend on the configuration
65 system, either to not compile an entire non-portable source where it will not
66 work, or to provide an appropriate #ifdef macro.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
67
691c8920 » chipdude
2006-09-05 Move pdd07 out of clip
68 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
69
cefc7d77 » coke
2007-05-30 RT# 42616 -
70 Perl code must be written for Perl 5.8.0 and all later versions.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
71
cefc7d77 » coke
2007-05-30 RT# 42616 -
72 Perl code may use features not available in Perl 5.8.0 only if it is not vital
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
73 to Parrot, and if it uses C<$^O> and C<$]> to degrade or fail gracefully when
74 it is run where the features it depends on are not available.
691c8920 » chipdude
2006-09-05 Move pdd07 out of clip
75
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
76 =back
691c8920 » chipdude
2006-09-05 Move pdd07 out of clip
77
78
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
79 =head3 Code Formatting
691c8920 » chipdude
2006-09-05 Move pdd07 out of clip
80
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
81 The following I<must> apply:
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
82
83 =over 4
84
85 =item *
86
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
87 Source line width is limited to 100 characters. Exceptions can be made for
88 technical requirements, but not for style reasons. And please bear in mind
89 that very long lines I<can> be hard to read.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
90
91 =item *
92
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
93 Indentation must consist only of spaces. (Tab characters just complicate
94 things.)
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
95
96 =item *
97
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
98 C and Perl code must be indented four columns per nesting level.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
99
100 =item *
101
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
102 Preprocessor #directives must be indented two columns per nesting level, with
103 two exceptions: neither PARROT_IN_CORE nor the outermost _GUARD #ifdefs cause
104 the level of indenting to increase.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
105
106 =item *
107
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
108 Labels (including case labels) must be outdented two columns relative to the
109 code they label.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
110
111 =item *
112
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
113 Closing braces for control structures must line up vertically with the
114 start of the control structures; e.g. C<}> that closes an C<if> must
115 line up with the C<if>.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
116
117 =item *
118
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
119 Long lines, when split, must use at least one extra level of indentation on
120 the continued line.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
121
122 =item *
123
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
124 Cuddled C<else>s are forbidden: i.e. avoid C<} else {> .
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
125
df070fa9 » particle
2007-11-02 [PDD07]: protecting expressions in macros by wrapping macro arguments…
126 =item *
127
6d989e71 » bschmalhofer
2008-03-05 [doc]
128 C macro parameters must be parenthesized in macro bodies, to allow expressions
df070fa9 » particle
2007-11-02 [PDD07]: protecting expressions in macros by wrapping macro arguments…
129 passed as arguments; e.g.:
130
041b2571 » cotto
2009-04-10 [PMC] PMC_pmc_val is history
131 #define POBJ_FLAG(n) ((UINTVAL)1 << (n))
df070fa9 » particle
2007-11-02 [PDD07]: protecting expressions in macros by wrapping macro arguments…
132
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
133 =back
134
135
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
136 The following I<should> apply:
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
137
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
138 =over 4
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
139
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
140 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
141
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
142 In function definitions, the function name must be on the left margin, with
143 the return type on the previous line.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
144
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
145 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
146
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
147 In function declarations (e.g. in header files), the function name must be on
148 the same line as the return type.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
149
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
150 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
151
dccaa83a » chipdude
2006-11-14 Incremental improvement to pdd07 "coding standards":
152 Pointer types should be written with separation between the star and the base
d4e13f7c » chromatic
2007-05-22 Minor corrections from Bram Geron (RT #42986).
153 type, e.g. C<Interp *foo>, but not C<Interp* foo>.
dccaa83a » chipdude
2006-11-14 Incremental improvement to pdd07 "coding standards":
154
155 =item *
156
fd5ea4fb » chromatic
2006-11-17 [PDD] Removed further ambiguity from keyword/function and parenthesis…
157 To distinguish keywords from function calls visually, there should be at least
158 one space between a C keyword and any subsequent open parenthesis, e.g.
159 C<return (x+y)*2>. There should be no space between a function name and the
160 following open parenthesis, e.g. C<z = foo(x+y)*2>
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
161
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
162 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
163
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
164 Use patterns of formatting to indicate patterns of semantics. Similar items
165 should look similar, as the language permits. Note that some dimensions of
166 similarity are incidental, not worth emphasizing; e.g. "these are all ints".
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
167
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
168 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
169
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
170 Binary operators (except C<.> and C<< -> >>) should have at least one space on
171 either side; there should be no space between unary operators and their
172 operands; parentheses should not have space immediately after the opening
173 parenthesis nor immediately before the closing parenthesis; commas should have
174 at least one space after, but not before; e.g.:
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
175
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
176 x = (a-- + b) * f(c, d / e.f)
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
177
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
178 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
179
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
180 Use vertical alignment for clarity of parallelism. Compare this (bad):
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
181
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
182 foo = 1 + 100;
183 x = 100 + 1;
184 whatever = 100 + 100;
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
185
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
186 ... to this (good):
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
187
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
188 foo = 1 + 100;
189 x = 100 + 1;
190 whatever = 100 + 100;
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
191
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
192 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
193
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
194 Do not routinely put single statements in statement blocks.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
195
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
196 (Note that formatting consistency trumps this rule. For example, a long
197 C<if>/C<else if> chain is easier to read if all (or none) of the conditional
198 code is in blocks.)
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
199
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
200 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
201
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
202 Return values should not be parenthesized without need. It may be necessary
203 to parenthesize a long return expression so that a smart editor will properly
204 indent it.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
205
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
206 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
207
4e45fb8c » particle
2006-10-16 [PDD07]: fix typo
208 When assigning inside a conditional, use extra parentheses,
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
209 e.g. C<if (a && (b = c)) ...> or C<if ((a = b)) ...>.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
210
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
211 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
212
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
213 When splitting a long line at a binary operator (other than comma), the split
283a51ff » paultcochrane
2007-09-14 [pdd] (pdd07) Added an example of splitting a long line before an ope…
214 should be I<before> the operator, so that the continued line looks like one,
215 e.g.:
216
217 something_long_here = something_very_long + something_else_also_long
218 - something_which_also_could_be_long;
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
219
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
220 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
221
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
222 When splitting a long line inside parentheses (or brackets), the continuation
223 should be indented to the right of the innermost unclosed punctuation, e.g.:
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
224
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
225 z = foo(bar + baz(something_very_long_here
226 * something_else_very_long),
227 corge);
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
228
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
229 =back
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
230
231
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
232 =head3 Code Structure
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
233
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
234 The following I<must> apply:
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
235
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
236 =over 4
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
237
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
238 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
239
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
240 C code must use C-style comments only, i.e. C</* comment */>. (Not all C
241 compilers handle C++-style comments.)
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
242
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
243 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
244
dccaa83a » chipdude
2006-11-14 Incremental improvement to pdd07 "coding standards":
245 Structure types must have tags.
246
247 =item *
248
249 Functions must have prototypes in scope at the point of use. Prototypes for
6d989e71 » bschmalhofer
2008-03-05 [doc]
250 extern functions must appear only in header files. If static functions are
dccaa83a » chipdude
2006-11-14 Incremental improvement to pdd07 "coding standards":
251 defined before use, their definitions serve as prototypes.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
252
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
253 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
254
6d989e71 » bschmalhofer
2008-03-05 [doc]
255 Parameters in function prototypes must be named. These names should match the
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
256 parameters in the function definition.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
257
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
258 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
259
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
260 Variable names must be included for all function parameters in the function
261 declarations.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
262
81c1d184 » paultcochrane
2007-05-08 [docs] Added coding standard text concerning guard preprocessor direc…
263 =item *
264
609281e4 » particle
2007-05-08 #42903: [PATCH] Add guards to the rest of the headerfiles
265 Header files must be wrapped with guard macros to prevent header redefinition.
266 The guard macro must begin with C<PARROT_>, followed by unique and descriptive
6d989e71 » bschmalhofer
2008-03-05 [doc]
267 text identifying the header file (usually the directory path and filename),
609281e4 » particle
2007-05-08 #42903: [PATCH] Add guards to the rest of the headerfiles
268 and end with a C<_GUARD> suffix. The matching C<#endif> must have the guard
81c1d184 » paultcochrane
2007-05-08 [docs] Added coding standard text concerning guard preprocessor direc…
269 macro name in a comment, to prevent confusion. For example, a file named
609281e4 » particle
2007-05-08 #42903: [PATCH] Add guards to the rest of the headerfiles
270 F<parrot/foo.h> might look like:
81c1d184 » paultcochrane
2007-05-08 [docs] Added coding standard text concerning guard preprocessor direc…
271
272 #ifndef PARROT_FOO_H_GUARD
609281e4 » particle
2007-05-08 #42903: [PATCH] Add guards to the rest of the headerfiles
273 #define PARROT_FOO_H_GUARD
274
275 #include "parrot/config.h"
276 #ifdef PARROT_HAS_FEATURE_FOO
277 # define FOO_TYPE bar
81c1d184 » paultcochrane
2007-05-08 [docs] Added coding standard text concerning guard preprocessor direc…
278 typedef struct foo {
609281e4 » particle
2007-05-08 #42903: [PATCH] Add guards to the rest of the headerfiles
279 ...
81c1d184 » paultcochrane
2007-05-08 [docs] Added coding standard text concerning guard preprocessor direc…
280 } foo_t;
609281e4 » particle
2007-05-08 #42903: [PATCH] Add guards to the rest of the headerfiles
281 #endif /* PARROT_HAS_FEATURE_FOO */
282
81c1d184 » paultcochrane
2007-05-08 [docs] Added coding standard text concerning guard preprocessor direc…
283 #endif /* PARROT_FOO_H_GUARD */
284
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
285 =back
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
286
287
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
288 The following I<should> apply
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
289
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
290 =over 4
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
291
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
292 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
293
dccaa83a » chipdude
2006-11-14 Incremental improvement to pdd07 "coding standards":
294 Structure types should have typedefs with the same name as their tags, e.g.:
295
296 typedef struct Foo {
297 ...
298 } Foo;
299
300 =item *
301
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
302 Avoid double negatives, e.g. C<#ifndef NO_FEATURE_FOO>.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
303
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
304 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
305
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
306 Do not compare directly against NULL, 0, or FALSE. Instead, write a boolean
307 test, e.g. C<if (!foo) ...>.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
308
a62a3096 » petdance
2007-12-17 added note about checking strcmp() as a boolean
309 However, the sense of the expression being checked must be a boolean.
310 Specifically, C<strcmp()> and its brethren are three-state returns.
311
312 if ( !strcmp(x,y) ) # BAD, checks for if x and y match, but looks
313 # like it is checking that they do NOT match.
314 if ( strcmp(x,y) == 0 ) # GOOD, checks proper return value
315 if ( STREQ(x,y) ) # GOOD, uses boolean wrapper macro
316
dccaa83a » chipdude
2006-11-14 Incremental improvement to pdd07 "coding standards":
317 (Note: C<PMC *> values should be checked for nullity with the C<PMC_IS_NULL>
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
318 macro, unfortunately leading to violations of the double-negative rule.)
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
319
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
320 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
321
3b33595d » paultcochrane
2007-09-17 [pdd] Applied changes recommended by Allison Randal on parrot-porters.
322 Avoid dependency on "FIXME" and "TODO" labels: use the external bug tracking
323 system. If a bug must be fixed soon, use "XXX" B<and> put a ticket in the
1c852017 » jkeenan
2009-11-21 Change documentation to reflect closing of RT in favor of Trac.
324 bug tracking system. This means that each "XXX" should have a Trac ticket
3b33595d » paultcochrane
2007-09-17 [pdd] Applied changes recommended by Allison Randal on parrot-porters.
325 number next to it.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
326
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
327 =back
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
328
329
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
330 =head3 Smart Editor Style Support
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
331
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
332 All developers using Emacs must ensure that their Emacs instances load the
97757a34 » chipdude
2006-09-05 Commit initial version of parrot.el,
333 elisp source file F<editor/parrot.el> before opening Parrot source files.
334 See L<editor/README.pod> for instructions.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
335
97757a34 » chipdude
2006-09-05 Commit initial version of parrot.el,
336 All source files must end with an editor instruction coda:
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
337
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
338 =over 4
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
339
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
340 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
341
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
342 C source files, and files largely consisting of C (e.g. yacc, lex, PMC, and
97757a34 » chipdude
2006-09-05 Commit initial version of parrot.el,
343 opcode source files), must end with this coda:
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
344
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
345 /*
346 * Local variables:
347 * c-file-style: "parrot"
348 * End:
349 * vim: expandtab shiftwidth=4:
350 */
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
351
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
352 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
353
f4250a1b » fperrad
2009-01-29 [codingstd] add check of Makefile coda
354 Make source files must end with this coda:
355
356 # Local Variables:
357 # mode: makefile
358 # End:
359 # vim: ft=make:
360
361 =item *
362
97757a34 » chipdude
2006-09-05 Commit initial version of parrot.el,
363 Perl source files must end with this coda:
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
364
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
365 # Local Variables:
366 # mode: cperl
367 # cperl-indent-level: 4
368 # fill-column: 100
369 # End:
370 # vim: expandtab shiftwidth=4:
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
371
2cbcd7d2 » paultcochrane
2007-04-01 [docs] Added a note about Perl source code with __END__ or __DATA__ b…
372 B<Exception>: Files with C<__END__> or C<__DATA__> blocks do not require the
373 coda. This is at least until there is some consensus as to how solve the
374 issue of using editor hints in files with such blocks.
375
deb479ff » allisonrandal
2007-03-17 [pdd]: Add editor coda for PIR files to coding standards.
376 =item *
377
378 PIR source files should end with this coda:
379
380 # Local Variables:
381 # mode: pir
382 # fill-column: 100
383 # End:
b894af0c » coke
2008-02-17 [codingstd]
384 # vim: expandtab shiftwidth=4 ft=pir:
deb479ff » allisonrandal
2007-03-17 [pdd]: Add editor coda for PIR files to coding standards.
385
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
386 =back
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
387
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
388 {{ XXX - Proper formatting and syntax coloring of C code under Emacs requires
389 that Emacs know about typedefs. We should provide a simple script to update a
390 list of typedefs, and parrot.el should read it or contain it. }}
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
391
392
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
393 =head3 Portability
dccaa83a » chipdude
2006-11-14 Incremental improvement to pdd07 "coding standards":
394
395 Parrot runs on many, many platforms, and will no doubt be ported to ever more
396 bizarre and obscure ones over time. You should never assume an operating
397 system, processor architecture, endian-ness, size of standard type, or
398 anything else that varies from system to system.
399
400 Since most of Parrot's development uses GNU C, you might accidentally depend
401 on a GNU feature without noticing. To avoid this, know what features of gcc
402 are GNU extensions, and use them only when they're protected by #ifdefs.
403
404
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
405 =head3 Defensive Programming
dccaa83a » chipdude
2006-11-14 Incremental improvement to pdd07 "coding standards":
406
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
407 =head4 Use Parrot data structures instead of C strings and arrays
dccaa83a » chipdude
2006-11-14 Incremental improvement to pdd07 "coding standards":
408
409 C arrays, including strings, are very sharp tools without safety guards, and
410 Parrot is a large program maintained by many people. Therefore:
411
412 Don't use a C<char *> when a Parrot STRING would suffice. Don't use a C array
501ff462 » paultcochrane
2007-09-11 [pdd] Minor textual and formatting cleanups.
413 when a Parrot array PMC would suffice. If you do use a C<char *> or C array,
dccaa83a » chipdude
2006-11-14 Incremental improvement to pdd07 "coding standards":
414 check and recheck your code for even the slightest possibility of buffer
415 overflow or memory leak.
416
417 Note that efficiency of some low-level operations may be a reason to break
418 this rule. Be prepared to justify your choices to a jury of your peers.
419
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
420 =head4 Pass only C<unsigned char> to C<isxxx()> and C<toxxx()>
dccaa83a » chipdude
2006-11-14 Incremental improvement to pdd07 "coding standards":
421
9c4c784d » chromatic
2007-03-31 r2658@waterwheel: chromatic | 2007-03-30 22:37:22 -0700
422 Pass only values in the range of C<unsigned char> (and the special value -1,
dccaa83a » chipdude
2006-11-14 Incremental improvement to pdd07 "coding standards":
423 a.k.a. C<EOF>) to the isxxx() and toxxx() library functions. Passing signed
424 characters to these functions is a very common error and leads to incorrect
425 behavior at best and crashes at worst. And under most of the compilers Parrot
426 targets, C<char> I<is> signed.
427
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
428 =head4 The C<const> keyword on arguments
dccaa83a » chipdude
2006-11-14 Incremental improvement to pdd07 "coding standards":
429
430 Use the C<const> keyword as often as possible on pointers. It lets
431 the compiler know when you intend to modify the contents of something.
432 For example, take this definition:
433
434 int strlen(const char *p);
435
436 The C<const> qualifier tells the compiler that the argument will not be
437 modified. The compiler can then tell you that this is an uninitialized
438 variable:
439
440 char *p;
441 int n = strlen(p);
442
443 Without the C<const>, the compiler has to assume that C<strlen()> is
444 actually initializing the contents of C<p>.
445
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
446 =head4 The C<const> keyword on variables
dccaa83a » chipdude
2006-11-14 Incremental improvement to pdd07 "coding standards":
447
448 If you're declaring a temporary pointer, declare it C<const>, with the
449 const to the right of the C<*>, to indicate that the pointer should not
450 be modified.
451
452 Wango * const w = get_current_wango();
9c4c784d » chromatic
2007-03-31 r2658@waterwheel: chromatic | 2007-03-30 22:37:22 -0700
453 w->min = 0;
454 w->max = 14;
dccaa83a » chipdude
2006-11-14 Incremental improvement to pdd07 "coding standards":
455 w->name = "Ted";
456
3c9e3858 » Util
2009-03-06 [docs] Typo corrections
457 This prevents you from modifying C<w> inadvertently.
dccaa83a » chipdude
2006-11-14 Incremental improvement to pdd07 "coding standards":
458
459 new_wango = w++; /* Error */
460
461 If you're not going to modify the target of the pointer, put a C<const>
462 to the left of the type, as in:
463
464 const Wango * const w = get_current_wango();
465 if (n < wango->min || n > wango->max) {
466 /* do something */
467 }
468
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
469 =head4 Localizing variables
dccaa83a » chipdude
2006-11-14 Incremental improvement to pdd07 "coding standards":
470
471 Declare variables in the innermost scope possible.
472
473 if (foo) {
474 int i;
475 for (i = 0; i < n; i++)
476 do_something(i);
477 }
478
479 Don't reuse unrelated variables. Localize as much as possible, even if
480 the variables happen to have the same names.
481
482 if (foo) {
483 int i;
484 for (i = 0; i < n; i++)
485 do_something(i);
486 }
487 else {
488 int i;
489 for (i = 14; i > 0; i--)
490 do_something_else(i * i);
491 }
492
493 You could hoist the C<int i;> outside the test, but then you'd have an
494 C<i> that's visible after it's used, which is confusing at best.
495
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
496 =head3 Naming Conventions
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
497
498 =over 4
499
500 =item Filenames
501
b9261ad1 » cotto
2011-09-06 large batch of typo fixes, courtesy of pfusik++
502 Filenames must be assumed to be case-insensitive, in the sense that you
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
503 may not have two different files called F<Foo> and F<foo>. Normal source-code
504 filenames should be all lower-case; filenames with upper-case letters in them
c96dc1e6 » ayardley
2012-04-26 Updated file references to 'README.pod' (rather than to 'README').
505 are reserved for notice-me-first files such as F<README.pod>, and for files
506 which need some sort of pre-processing applied to them or which do the
507 preprocessing - e.g. a script F<foo.SH> might read F<foo.TEMPLATE> and output
508 F<foo.c>.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
509
510 The characters making up filenames must be chosen from the ASCII set
511 A-Z,a-z,0-9 plus .-_
512
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
513 An underscore should be used to separate words rather than a hyphen (-).
514 A file should not normally have more than a single '.' in it, and this
515 should be used to denote a suffix of some description. The filename must
516 still be unique if the main part is truncated to 8 characters and any
517 suffix truncated to 3 characters. Ideally, filenames should restricted
518 to 8.3 in the first place, but this is not essential.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
519
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
520 Each subsystem I<foo> should supply the following files. This
521 arrangement is based on the assumption that each subsystem will -- as
522 far as is practical -- present an opaque interface to all other
523 subsystems within the core, as well as to extensions and embeddings.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
524
525 =over 4
526
501ff462 » paultcochrane
2007-09-11 [pdd] Minor textual and formatting cleanups.
527 =item C<foo.h>
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
528
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
529 This contains all the declarations needed for external users of that API
530 (and nothing more), i.e. it defines the API. It is permissible for the
531 API to include different or extra functionality when used by other parts
532 of the core, compared with its use in extensions and embeddings. In this
533 case, the extra stuff within the file is enabled by testing for the
534 macro C<PARROT_IN_CORE>.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
535
501ff462 » paultcochrane
2007-09-11 [pdd] Minor textual and formatting cleanups.
536 =item C<foo_private.h>
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
537
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
538 This contains declarations used internally by that subsystem, and which
539 must only be included within source files associated the subsystem. This
540 file defines the macro C<PARROT_IN_FOO> so that code knows when it is
541 being used within that subsystem. The file will also contain all the
542 'convenience' macros used to define shorter working names for functions
543 without the perl prefix (see below).
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
544
501ff462 » paultcochrane
2007-09-11 [pdd] Minor textual and formatting cleanups.
545 =item C<foo_globals.h>
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
546
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
547 This file contains the declaration of a single structure containing the
548 private global variables used by the subsystem (see the section on
549 globals below for more details).
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
550
501ff462 » paultcochrane
2007-09-11 [pdd] Minor textual and formatting cleanups.
551 =item C<foo_bar.[ch]> etc.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
552
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
553 All other source files associated with the subsystem will have the
554 prefix C<foo_>.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
555
556 =back
557
558 =item Names of code entities
559
501ff462 » paultcochrane
2007-09-11 [pdd] Minor textual and formatting cleanups.
560 Code entities such as variables, functions, macros etc. (apart from strictly
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
561 local ones) should all follow these general guidelines.
562
563 =over 4
564
565 =item *
566
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
567 Multiple words or components should be separated with underscores rather
568 than using tricks such as capitalization, e.g. C<new_foo_bar> rather
569 than C<NewFooBar> or (gasp) C<newfoobar>.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
570
571 =item *
572
6004150d » allisonrandal
2006-12-17 Updated coding standard for naming externally visible functions,
573 The names of entities should err on the side of verbosity, e.g.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
574 C<create_foo_from_bar()> in preference to C<ct_foo_bar()>. Avoid cryptic
575 abbreviations wherever possible.
576
577 =item *
578
501ff462 » paultcochrane
2007-09-11 [pdd] Minor textual and formatting cleanups.
579 All entities should be prefixed with the name of the subsystem in which they
580 appear, e.g. C<pmc_foo()>, C<struct io_bar>.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
581
6004150d » allisonrandal
2006-12-17 Updated coding standard for naming externally visible functions,
582 =item *
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
583
6004150d » allisonrandal
2006-12-17 Updated coding standard for naming externally visible functions,
584 Functions with external visibility should be of the form C<Parrot_foo>,
585 and should only use typedefs with external visibility (or types defined
586 in C89). Generally these functions should not be used inside the core,
587 but this is not a hard and fast rule.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
588
589 =item *
590
6004150d » allisonrandal
2006-12-17 Updated coding standard for naming externally visible functions,
591 Variables and structure names should be all lower-case, e.g. C<pmc_foo>.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
592
593 =item *
594
595 Structure elements should be all lower-case, and the first component of the
596 name should incorporate the structure's name or an abbreviation of it.
597
598 =item *
599
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
600 Typedef names should be lower-case except for the first letter, e.g.
601 C<Foo_bar>. The exception to this is when the first component is a
602 short abbreviation, in which case the whole first component may be made
603 uppercase for readability purposes, e.g. C<IO_foo> rather than
604 C<Io_foo>. Structures should generally be typedefed.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
605
606 =item *
607
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
608 Macros should have their first component uppercase, and the majority of
609 the remaining components should be likewise. Where there is a family of
610 macros, the variable part can be indicated in lowercase, e.g.
611 C<PMC_foo_FLAG>, C<PMC_bar_FLAG>, ....
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
612
613 =item *
614
6004150d » allisonrandal
2006-12-17 Updated coding standard for naming externally visible functions,
615 A macro which defines a flag bit should be suffixed with C<_FLAG>, e.g.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
616 C<PMC_readonly_FLAG> (although you probably want to use an C<enum> instead.)
617
618 =item *
619
6004150d » allisonrandal
2006-12-17 Updated coding standard for naming externally visible functions,
620 A macro which tests a flag bit should be suffixed with C<_TEST>, e.g. C<if
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
621 (PMC_readonly_TEST(foo)) ...>
622
623 =item *
624
6004150d » allisonrandal
2006-12-17 Updated coding standard for naming externally visible functions,
625 A macro which sets a flag bit should be suffixed with C<_SET>, e.g.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
626 C<PMC_readonly_SET(foo);>
627
628 =item *
629
6004150d » allisonrandal
2006-12-17 Updated coding standard for naming externally visible functions,
630 A macro which clears a flag bit should be suffixed with C<_CLEAR>, e.g.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
631 C<PMC_readonly_CLEAR(foo);>
632
633 =item *
634
6004150d » allisonrandal
2006-12-17 Updated coding standard for naming externally visible functions,
635 A macro defining a mask of flag bits should be suffixed with C<_MASK>, e.g.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
636 C<foo &= ~PMC_STATUS_MASK> (but see notes on extensibility below).
637
638 =item *
639
640 Macros can be defined to cover common flag combinations, in which case they
501ff462 » paultcochrane
2007-09-11 [pdd] Minor textual and formatting cleanups.
641 should have C<_SETALL>, C<_CLEARALL>, C<_TESTALL> or C<_TESTANY> suffixes as
642 appropriate, to indicate aggregate bits, e.g. C<PMC_valid_CLEARALL(foo)>.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
643
644 =item *
645
646 A macro defining an auto-configuration value should be prefixed with C<HAS_>,
6004150d » allisonrandal
2006-12-17 Updated coding standard for naming externally visible functions,
647 e.g. C<HAS_BROKEN_FLOCK>, C<HAS_EBCDIC>.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
648
649 =item *
650
3b33595d » paultcochrane
2007-09-17 [pdd] Applied changes recommended by Allison Randal on parrot-porters.
651 A macro indicating the compilation 'location' should be prefixed with
652 C<IN_>, e.g. C<PARROT_IN_CORE>, C<PARROT_IN_PMC>, C<PARROT_IN_X2P>.
653 Individual include file visitations should be marked with C<PARROT_IN_FOO_H>
654 for file C<foo.h>
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
655
656 =item *
657
658 A macro indicating major compilation switches should be prefixed with C<USE_>,
3b33595d » paultcochrane
2007-09-17 [pdd] Applied changes recommended by Allison Randal on parrot-porters.
659 e.g. C<PARROT_USE_STDIO>, C<USE_MULTIPLICITY>.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
660
661 =item *
662
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
663 A macro that may declare stuff and thus needs to be at the start of a
664 block should be prefixed with C<DECL_>, e.g. C<DECL_SAVE_STACK>. Note
665 that macros which implicitly declare and then use variables are strongly
666 discouraged, unless it is essential for portability or extensibility.
667 The following are in decreasing preference style-wise, but increasing
668 preference extensibility-wise.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
669
670 { Stack sp = GETSTACK; x = POPSTACK(sp) ... /* sp is an auto variable */
671 { DECL_STACK(sp); x = POPSTACK(sp); ... /* sp may or may not be auto */
672 { DECL_STACK; x = POPSTACK; ... /* anybody's guess */
673
674
675 =back
676
677 =item Global Variables
678
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
679 Global variables must never be accessed directly outside the subsystem
680 in which they are used. Some other method, such as accessor functions,
681 must be provided by that subsystem's API. (For efficiency the 'accessor
682 functions' may occasionally actually be macros, but then the rule still
683 applies in spirit at least).
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
684
685 All global variables needed for the internal use of a particular subsystem
501ff462 » paultcochrane
2007-09-11 [pdd] Minor textual and formatting cleanups.
686 should all be declared within a single struct called C<foo_globals> for
687 subsystem C<foo>. This structure's declaration is placed in the file
688 C<foo_globals.h>. Then somewhere a single compound structure will be
689 declared which has as members the individual structures from each subsystem.
690 Instances of this structure are then defined as a one-off global variable,
691 or as per-thread instances, or whatever is required.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
692
693 [Actually, three separate structures may be required, for global,
694 per-interpreter and per-thread variables.]
695
696 Within an individual subsystem, macros are defined for each global variable of
697 the form C<GLOBAL_foo> (the name being deliberately clunky). So we might for
698 example have the following macros:
699
700 /* perl_core.h or similar */
701
702 #ifdef HAS_THREADS
703 # define GLOBALS_BASE (aTHX_->globals)
704 #else
3b33595d » paultcochrane
2007-09-17 [pdd] Applied changes recommended by Allison Randal on parrot-porters.
705 # define GLOBALS_BASE (Parrot_globals)
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
706 #endif
707
708 /* pmc_private.h */
709
710 #define GLOBAL_foo GLOBALS_BASE.pmc.foo
711 #define GLOBAL_bar GLOBALS_BASE.pmc.bar
712 ... etc ...
713
714 =back
715
716
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
717 =head3 Code Comments
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
718
719 The importance of good code documentation cannot be stressed enough. To make
720 your code understandable by others (and indeed by yourself when you come to
6d989e71 » bschmalhofer
2008-03-05 [doc]
721 make changes a year later), the following conventions apply to all source
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
722 files.
723
724 =over 4
725
726 =item Developer files
727
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
728 Each source file (e.g. a F<foo.c>, F<foo.h> pair), should contain inline
f417097b » allisonrandal
2009-03-10 [doc] Updating coding standards on Pod documentation to match current
729 Pod documentation containing information on the implementation decisions
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
730 associated with the source file. (Note that this is in contrast to PDDs,
731 which describe design decisions). In addition, more discussive
732 documentation can be placed in F<*.pod> files in the F<docs/dev>
733 directory. This is the place for mini-essays on how to avoid overflows
734 in unsigned arithmetic, or on the pros and cons of differing hash
735 algorithms, and why the current one was chosen, and how it works.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
736
737 In principle, someone coming to a particular source file for the first time
738 should be able to read the inline documentation file and gain an immediate
739 overview of what the source file is for, the algorithms it implements, etc.
740
f417097b » allisonrandal
2009-03-10 [doc] Updating coding standards on Pod documentation to match current
741 The Pod documentation should follow the layout:
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
742
743 =over 4
744
f417097b » allisonrandal
2009-03-10 [doc] Updating coding standards on Pod documentation to match current
745 =item Title
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
746
f417097b » allisonrandal
2009-03-10 [doc] Updating coding standards on Pod documentation to match current
747 =head1 Foo
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
748
f417097b » allisonrandal
2009-03-10 [doc] Updating coding standards on Pod documentation to match current
749 =item Synopsis
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
750
751 When appropriate, some simple examples of usage.
752
f417097b » allisonrandal
2009-03-10 [doc] Updating coding standards on Pod documentation to match current
753 =item Description
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
754
755 A description of the contents of the file, how the implementation works, data
756 structures and algorithms, and anything that may be of interest to your
6004150d » allisonrandal
2006-12-17 Updated coding standard for naming externally visible functions,
757 successors, e.g. benchmarks of differing hash algorithms, essays on how to do
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
758 integer arithmetic.
759
f417097b » allisonrandal
2009-03-10 [doc] Updating coding standards on Pod documentation to match current
760 =item See Also
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
761
501ff462 » paultcochrane
2007-09-11 [pdd] Minor textual and formatting cleanups.
762 Links to pages and books that may contain useful information relevant to the
763 stuff going on in the code -- e.g. the book you stole the hash function from.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
764
765 =back
766
b8e2ab0a » bschmalhofer
2008-12-31 [codingstd] Satisfy trailing_space.t and pdd_format.t
767 Don't include author information in individual files. Author information
768 can be added to the CREDITS file. (Languages are an exception to this rule,
769 and may follow whatever convention they choose.)
47ae2d29 » allisonrandal
2008-12-31 [pdd] Remove the 'HISTORY' section from expected documentation, as it…
770
b2998fad » allisonrandal
2009-04-16 [pdd] Add a note on License and Copyright sections in Pod documentation.
771 Don't include Pod sections for License or Copyright in individual files.
772
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
773 =item Per-section comments
774
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
775 If there is a collection of functions, structures or whatever which are
776 grouped together and have a common theme or purpose, there should be a
777 general comment at the start of the section briefly explaining their
778 overall purpose. (Detailed essays should be left to the developer file).
779 If there is really only one section, then the top-of-file comment
780 already satisfies this requirement.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
781
782 =item Per-entity comments
783
784 Every non-local named entity, be it a function, variable, structure, macro or
8c0b329d » Nicholas Clark
2006-09-09 1 grammar fix, 1 typo fix.
785 whatever, must have an accompanying comment explaining its purpose. This
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
786 comment must be in the special format described below, in order to allow
787 automatic extraction by tools - for example, to generate per API man pages,
788 B<perldoc -f> style utilities and so on.
789
790 Often the comment need only be a single line explaining its purpose, but
791 sometimes more explanation may be needed. For example, "return an Integer Foo
792 to its allocation pool" may be enough to demystify the function C<del_I_foo()>
793
794 Each comment should be of the form
795
796 /*
797
798 =item C<function(arguments)>
799
800 Description.
801
802 =cut
803
804 */
805
c06deae6 » coke
2010-06-16 Remove unused "--delete" option to tools/docs/write_docs.pl, we have …
806 This inline Pod documentation is transformed to HTML with:
f417097b » allisonrandal
2009-03-10 [doc] Updating coding standards on Pod documentation to match current
807
808 $ make html
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
809
810 =item Optimizations
811
812 Whenever code has deliberately been written in an odd way for performance
813 reasons, you should point this out - if nothing else, to avoid some poor
814 schmuck trying subsequently to replace it with something 'cleaner'.
815
816 /* The loop is partially unrolled here as it makes it a lot faster.
955f01e0 » paultcochrane
2007-06-03 [docs] References to developer files have now been updated to point to
817 * See the file in docs/dev for the full details
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
818 */
819
820 =item General comments
821
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
822 While there is no need to go mad commenting every line of code, it is
823 immensely helpful to provide a "running commentary" every 10 lines or so
824 if nothing else, this makes it easy to quickly locate a specific chunk
825 of code. Such comments are particularly useful at the top of each major
826 branch, e.g.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
827
828 if (FOO_bar_BAZ(**p+*q) <= (r-s[FOZ & FAZ_MASK]) || FLOP_2(z99)) {
829 /* we're in foo mode: clean up lexicals */
830 ... (20 lines of gibberish) ...
831 }
832 else if (...) {
833 /* we're in bar mode: clean up globals */
834 ... (20 more lines of gibberish) ...
835 }
836 else {
837 /* we're in baz mode: self-destruct */
838 ....
839 }
840
ab1403a3 » allisonrandal
2009-04-16 [pdd] Add a description of our coding standards for copyright notices in
841 =item Copyright notice
842
a5f1d8be » jkeenan
2009-04-16 Copyright statement goes on line 2 if line 1 is a shebang line.
843 The first line of every file (or the second line if the first line is a
844 I<shebang> line such as C<#!/usr/bin/perl>) should be a copyright notice, in
845 the comment style appropriate to the file type. It should list the first year
846 the file was created and the last year the file was modified. (This isn't
847 necessarily the current year, the file might not have been modified this
848 year.)
ab1403a3 » allisonrandal
2009-04-16 [pdd] Add a description of our coding standards for copyright notices in
849
850 /* Copyright (C) 2001-2008, Parrot Foundation. */
851
852 For files that were newly added this year, just list the current year.
853
854 /* Copyright (C) 2009, Parrot Foundation. */
855
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
856 =back
857
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
858 =head3 Extensibility
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
859
47ae2d29 » allisonrandal
2008-12-31 [pdd] Remove the 'HISTORY' section from expected documentation, as it…
860 Over the lifetime of Parrot, the source code will undergo many major changes
861 never envisaged by its original authors. To this end, your code should balance
862 out the assumptions that make things possible, fast or small, with the
863 assumptions that make it difficult to change things in future. This is
864 especially important for parts of the code which are exposed through APIs --
865 the requirements of source or binary compatibility for such things as
866 extensions can make it very hard to change things later on.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
867
868 For example, if you define suitable macros to set/test flags in a struct, then
869 you can later add a second word of flags to the struct without breaking source
870 compatibility. (Although you might still break binary compatibility if you're
871 not careful.) Of the following two methods of setting a common combination of
872 flags, the second doesn't assume that all the flags are contained within a
873 single field:
874
875 foo->flags |= (FOO_int_FLAG | FOO_num_FLAG | FOO_str_FLAG);
876 FOO_valid_value_SETALL(foo);
877
501ff462 » paultcochrane
2007-09-11 [pdd] Minor textual and formatting cleanups.
878 Similarly, avoid using a C<char*> (or C<{char*,length}>) if it is feasible
879 to later use a C<PMC *> at the same point: c.f. UTF-8 hash keys in Perl 5.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
880
881 Of course, private code hidden behind an API can play more fast and loose than
882 code which gets exposed.
883
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
884 =head3 Performance
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
885
ce1c8a58 » allisonrandal
2007-09-15 [pdd] Trim down optimization guidelines in coding standards PDD.
886 We want Parrot to be fast. Very fast. But we also want it to be portable and
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
887 extensible. Based on the 90/10 principle, (or 80/20, or 95/5, depending on who
888 you speak to), most performance is gained or lost in a few small but critical
889 areas of code. Concentrate your optimization efforts there.
890
891 Note that the most overwhelmingly important factor in performance is in
892 choosing the correct algorithms and data structures in the first place. Any
893 subsequent tweaking of code is secondary to this. Also, any tweaking that is
894 done should as far as possible be platform independent, or at least likely to
895 cause speed-ups in a wide variety of environments, and do no harm elsewhere.
896
1b9db752 » jkeenan
2008-04-03 Make PPD conform to coding standard for PDDs (https://rt.perl.org/rt3…
897 If you do put an optimization in, time it on as many architectures as
898 you can, and be suspicious of it if it slows down on any of them!
899 Perhaps it will be slow on other architectures too (current and future).
900 Perhaps it wasn't so clever after all? If the optimization is platform
901 specific, you should probably put it in a platform-specific function in
902 a platform-specific file, rather than cluttering the main source with
903 zillions of #ifdefs.
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
904
905 And remember to document it.
906
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
907 =head2 Exemptions
77448fe4 » paultcochrane
2007-01-08 [pdd] Added a section explaining files to be considered exempt from the
908
909 Not all files can strictly fall under these guidelines as they are
910 automatically generated by other tools, or are external files included in
911 the Parrot repository for convenience. Such files include the C header and
912 source files automatically generated by (f)lex and yacc/bison, and some of
6d989e71 » bschmalhofer
2008-03-05 [doc]
913 the Perl modules under the F<lib/> directory.
77448fe4 » paultcochrane
2007-01-08 [pdd] Added a section explaining files to be considered exempt from the
914
915 To exempt a file (or directory of files) from checking by the coding
916 standards tests, one must edit the appropriate exemption list within
917 C<lib/Parrot/Distribution.pm> (in either of the methods C<is_c_exemption()>
918 or C<is_perl_exemption()>). One can use wildcards in the list to exempt,
919 for example, all files under a given directory.
920
d5007adb » allisonrandal
2009-02-08 [doc] Abandoning daft Perl 5-style documentation headings.
921 =head2 References
a4f9bead » cotto
2008-09-06 [pdd] make non-draft PDDs pass pdd_format.t
922
fba2bc19 » coke
2010-04-14 PDD cleanup (TT #1536); Remove maintainer, changes sections.
923 None.
a4f9bead » cotto
2008-09-06 [pdd] make non-draft PDDs pass pdd_format.t
924
cd215a2a » chipdude
2006-09-05 About 25% done with update of pdd07.
925 =cut
62a3c410 » chipdude
2006-09-05 Move pdd07 out of clip
926
5d75ebcb » rurban
2008-09-12 [pdd] make all pdds pass t/codingstd/perlcritic.t and pdd_format.t: t…
927 __END__
928 Local Variables:
929 fill-column:78
930 End:
931 vim: expandtab shiftwidth=4:
Something went wrong with that request. Please try again.