1 karl 1.1 <html>
2
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=windows-1252">
5 <meta name="GENERATOR" content="Microsoft FrontPage 4.0">
6 <meta name="ProgId" content="FrontPage.Editor.Document">
7 <title>Pegasus Project Working Paper</title>
8 </head>
9
10 <body>
11
12 <H1 align="center">Pegasus Project Working Paper</H1>
13
14 <H1 align="center">Programming Guidelines For the Pegasus Project</H1>
15
16 <b>AUTHORS:</b> M. Brasher, K. Schopmeyer
17 <p><font size="1">Last Update <!--webbot bot="Timestamp"
|
18 mike 1.2 S-Type="EDITED" S-Format="%A, %B %d, %Y %I:%M %p" startspan -->Thursday, July 26, 2001 06:10 PM<!--webbot bot="Timestamp" i-CheckSum="6014" endspan -->
|
19 karl 1.1 </font></p>
20 <p>Revision Status</p>
21 <table border="1" width="80%">
22 <tr>
23 <td width="25%">Revision</td>
24 <td width="25%">Date</td>
25 <td width="25%">Author(s)</td>
26 <td width="25%">Reason</td>
27 </tr>
28 <tr>
29 <td width="25%">0.1</td>
30 <td width="25%">5 July 2001</td>
31 <td width="25%">M. brasher, K. Schopmeyer</td>
32 <td width="25%">first Draft</td>
33 </tr>
34 <tr>
|
35 mike 1.2 <td width="25%">0.2</td>
36 <td width="25%">24 July 2001</td>
37 <td width="25%">M. Brasher, K. Schopmeyer</td>
|
38 karl 1.1 <td width="25%"> </td>
39 </tr>
40 <tr>
|
41 mike 1.2 <td width="25%">0.3</td>
42 <td width="25%">26 July 2001</td>
43 <td width="25%">K. Schopmeyer</td>
44 <td width="25%">Add documentation on licensing.</td>
|
45 karl 1.1 </tr>
46 <tr>
47 <td width="25%"> </td>
48 <td width="25%"> </td>
49 <td width="25%"> </td>
50 <td width="25%"> </td>
51 </tr>
52 </table>
53
54 <h2>Introduction</h2>
55
56 <p>This document defines the basic set of guides and rules for programmers
57 contributing to the Pegasus Project</p>
58
59 <p>NOTE: This is a draft copy for comment.</p>
60
|
61 mike 1.2 <p>RULES and GUIDELINES - A number of the guidelines below are absolute rules
62 that we must follow in the Pegasus project. These are the things that will
63 help insure portability and effective interoperability of the components.</p>
64
65 <p>Other area are "guidelines" that we strongly suggest be followed
66 so that 1) the code will be readable and usable, 2) we develop a single look to
67 our source code, etc. In some cases, there may be reasons to bypass some
68 of these guidelines but we strongly encourage everybody to follow them.
69 In fact, if there is a real reason we will change to what the group wants and
70 suggestions.</p>
71
|
72 karl 1.1 <h2>Coding Conventions</h2>
73 <OL>
74 <LI><b>Indenting Code</b> - Indent by increments of 4 characters (with tabsize of
|
75 mike 1.2 8). Use the TAB character. This is the accepted norm for open source
76 code.
|
77 karl 1.1
78 <LI><b>Naming Conventions</b> - <font face="Courier New"> ThisIsAClassName</font> - no underscores.
79 <font face="Courier New">
80 thisIsAMethodName()</font> - no underscores.
81
82 Files Names should take advantage of case and avoid underscores.
83 Files should have the same name as the class (and same case).
84 <br>Prepend '_' to private members (including methods).
85 <LI><b>Code Line Length</b> - Lines should not span more than 80 columns.
86 When methods span more than 80 columns, do this:
87 <pre>
|
88 mike 1.2 void MyClass::myMethod(
89 const char* someReallyLongName,
90 const char* someOtherReallyLongName);
|
91 karl 1.1 </pre>
|
92 mike 1.2 <LI> Use "char* x" rather than "char *x". Either is normally legal for the
93 majority of compilers.
94 <LI><b>Use of <font face="Courier New">const</font></b>. Use <font face="Courier New"> const</font> whenever possible.
95 Use <font face="Courier New"> const</font> methods whenever possible.
|
96 karl 1.1 <LI><b>Braces</b> - Put opening brace on a line by itself. Braces must be aligned with control keyword:
97 <pre>
98 for(...)
99 {
100 ....
101 }
102 </pre>
103 Not this:
104 <pre> for (...)
105 {
106 ....
|
107 mike 1.2 }</pre>
108 or this:<pre> for (...){
109 ....
110 }</pre>
|
111 karl 1.1 <LI><b>Using Space</b> - No spaces after names.
112 <br>Separate functions with blank lines.
113 <pre> class X
114 {
115 public:
116 void f();
117 void g();
118 };</pre>
119 <p>
120
121 <LI> Not "void f ()" but "void f()".
122
123 <LI>Avoid this:<br>
124 <font face="Courier New">
125 callingMyFunction(blah,<br>
126 blah2,<br>
127 blah3);</font><br>
128 Do this:<br>
129 <font face="Courier New">callingMyFunction(<br>
130 blah,<br>
131 blah2,<br>
132 karl 1.1 blah3);</font>>/pre><br>
133 <LI>
134 <pre>Avoid this:
|
135 mike 1.2
|
136 karl 1.1 int x;
137 float y;
138 </pre>
139 <LI>Use 0 and not NULL.
140 <li>Don't separate return type onto its own line:
141
142 Avoid this:
143 <pre>
144 int
145 f()
146 {
147 ....
148 }
149 </pre>
150
151 <li><b>Comments</b> - Use /** */ rather than /// for DOC++.
152
153 <li><b>Conditional Compilation </b>- Avoid use of conditional compilation for obscuring platrform
154 differences. Use (or put) routines in appropriate platform files
155 or in the System*.cpp files in Common.
156 </ol>
157 karl 1.1 <h2>Testing</h2>
158
159 <p>Effective testing is essential to allowing a group to work together in a
160 common code environment. We have created a structure where unit and even system
161 level tests can be created and committed to the source tree as part of all
162 development. Each major directory section includes a tests subdirectory
163 with individual directories for tests. Please create and commit tests as part of
164 the normal environment wherever it is possible. All core code should include
165 tests created in this manner as well</p>
166
167 <p>If you change code to extend it or make corrections, please review the
168 corresponding tests code to 1) add tests to cover the problem corrected 2)
169 extend tests to cover the new code added.</p>
170
171 <p>Be mindful that the tests must run on all supported platforms and
172 that a commit may break another platform.</p>
173
174 <p>Tests must clean up the effect they have on the repository.</p>
175
176 Changes must work on all platforms. Commits must not break any
177 platform.
178 karl 1.1
179 Always write a regression test for everything.
|
180 mike 1.2 <p>No files with warnings should be committed to CVS.
|
181 karl 1.1
182 Test big changes on at least Windows and Unix (or Linux)
183
184 <h2>Committing Code to CVS</h2>
185
186 <p>Don't commit anything that breaks the build (try a clean slate
187 checkout and build). Remember that if the build is broken for you, it
188 is also broken for everybody that gets the new code.</p>
189
190 <p>Always build and run all regression tests before committing. </p>
191
192 <p>No binaries may be committed to repository. </p>
193
194 <p> There are a few exceptions to this rule but binary files cause problems</p>
195
196 <h2>Using Outside Code and Libraries</h2>
197
|
198 mike 1.2 <p>This is an open source project. All code that is contributed to this
|
199 karl 1.1 project must be open source and must be made available under the standard
200 license used by the Pegasus project. Do not use any outside libraries that do
201 not meet this criteria. Further, every reference to outside code make it
202 more complex for others to build and work with the project and introduces
203 potential portability problems. At the same time, there may be real
204 reasons to use outside code and libraries at times. Thus, for example, the
205 initial project used the ACE_wrappers libraries extensively but with the
206 objective of eventually providing a replacement. That replacement has been
|
207 mike 1.2 produced, partly because ACE was not available on all of the platforms.</p>
208
209 <p>All code submitted to the Pegasus core source libraries is to be made available
210 under the standard license used by Pegasus. If any code is to be taken
211 from other open source projects, we expect that the code recognize both the
212 requirements of the Pegasus standard license and the other license (ex. if we
213 were to share code with the Caldera OpenWBEM) project, we would have to show
214 both their license and our licenses.</p>
215
216 <p>All code input to the Pegasus project must include the license statement.</p>
217
218 <p>If there is a case of code that we want to use on the Pegasus project but
219 that is licensed outside of the above rules, it can be included only with the
220 specific permission of the Pegasus project management. We will be very
221 hesitant to do this since it could mean weakening the whole open source nature
222 of the project and would greatly complicate our license arrangements.</p>
|
223 karl 1.1
224 <h2>Using Make</h2>
225
226 <p>The Pegasus project has developed a consistent and portable make system that
227 allows bot localized and global builds on a wide variety of systems from Windows
228 to Unix to the tandem platforms today. This is based on 1) using the GNU
229 Make tool as the core of the make system, 2) minimining the use of other tools.
230 </p>
231
232 <p><<EXPLAIN THE MAKE SYSTEM OR REFERENCE DOC>>>
233 </p>
234
235 <p>All code must be reachable (built) from master makefile. Otherwise it will not be reached when doing mass substitutions, testings of
236 builds, and license changes.
237 </p>
238
239 <h2>DOCUMENTING
240 </h2>
241
242 <p><<<THIS SECTION NEED TO BE COMPLETED>>>
243 </p>
|
244 mike 1.2
245 <h2>Portability Issues</h2>
246
247 <OL>
248 <LI>In .h files the following identifiers must be surrounded by the PEGASUS_STD() macro (which
249 pretends std:: to the argument).<br>
250 <br>
251 <font face="Courier New"> ostream<br>
252 istream<br>
253 cout<br>
254 cerr<br>
255 </font><br>
256 Do not use this macro in .cpp files. Instead put the following<br>
257 at the beginning of the file:<br>
258 <br>
259 PEGASUS_USING_STD;<br>
260 <br>
261 <LI>The following does not compile with some compilers.<br>
262 <br>
263 class X<br>
264 {<br>
265 mike 1.2 public:<br>
266 <br>
267 static const Uint32 COLOR = 225;<br>
268 };<br>
269 <br>
270 Use this instead:<br>
271 <br>
272 class X<br>
273 {<br>
274 public:<br>
275 <br>
276 static const Uint32 COLOR;<br>
277 };<br>
278 <br>
279 And place this in the .cpp file:<br>
280 <br>
281 const Uint32 X::COLOR = 255;<br>
282 <br>
283 Or use enumerated types:<br>
284 <br>
285 class X<br>
286 mike 1.2 {<br>
287 public:<br>
288 <br>
289 enum { COLOR = 225 };<br>
290 };<br>
291 </OL>
|
292 karl 1.1
293 <h2>The Source Tree Structure</h2>
294
295 <p>We work from a single source tree in CVS. We have a fixed structure for
296 this structure.</p>
297
298 <p><<<THIS SECTION IS TBD>>></p>
299
300 <p> </p>
301
302 <p> </p>
303
304 <p>---END OF DOCUMENT--</p>
305
306 </body>
307
308 </html>
|
Return to
PegasusProgrammingGuidelines.htm
CVS log
Up to [Pegasus] / pegasus / doc / WorkPapers