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 karl 1.1.2.1 S-Type="EDITED" S-Format="%A, %B %d, %Y %I:%M %p" startspan -->Tuesday, July 24, 2001 08:48 PM<!--webbot bot="Timestamp" i-CheckSum="54098" 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 karl 1.1.2.1 <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 <td width="25%"> </td>
42 <td width="25%"> </td>
43 <td width="25%"> </td>
44 <td width="25%"> </td>
45 </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 karl 1.1 <p>NOTE: This is a draft copy for comment.</p>
60
|
61 karl 1.1.2.1 <p>RULES and Suggestions - 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 "suggestions" 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 suggestiions 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 karl 1.1.2.1 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 karl 1.1.2.1 void MyClass::myMethod(
89 const char* someReallyLongName,
90 const char* someOtherReallyLongName);
|
91 karl 1.1 </pre>
|
92 karl 1.1.2.1 <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 karl 1.1.2.1 }</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 karl 1.1.2.1
|
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 <p>No warnings should be committed.
181
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 <p>This is an opensource 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 produced, partly because ACE was not available on all of the platforms</p>
208
209 <h2>Using Make</h2>
210
211 <p>The Pegasus project has developed a consistent and portable make system that
212 allows bot localized and global builds on a wide variety of systems from Windows
213 to Unix to the tandem platforms today. This is based on 1) using the GNU
214 Make tool as the core of the make system, 2) minimining the use of other tools.
215 </p>
216
217 <p><<EXPLAIN THE MAKE SYSTEM OR REFERENCE DOC>>>
218 </p>
219
220 karl 1.1 <p>All code must be reachable (built) from master makefile. Otherwise it will not be reached when doing mass substitutions, testings of
221 builds, and license changes.
222 </p>
223
224 <h2>DOCUMENTING
225 </h2>
226
227 <p><<<THIS SECTION NEED TO BE COMPLETED>>>
228 </p>
|
229 karl 1.1.2.1
230 <h2>Portability Issues</h2>
231
232 <p>TBD</p>
|
233 karl 1.1
234 <h2>The Source Tree Structure</h2>
235
236 <p>We work from a single source tree in CVS. We have a fixed structure for
237 this structure.</p>
238
239 <p><<<THIS SECTION IS TBD>>></p>
240
241 <p> </p>
242
243 <p> </p>
244
245 <p>---END OF DOCUMENT--</p>
246
247 </body>
248
249 </html>
|
Return to
PegasusProgrammingGuidelines.htm
CVS log
Up to [Pegasus] / pegasus / doc / WorkPapers