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 S-Type="EDITED" S-Format="%A, %B %d, %Y %I:%M %p" startspan -->Thursday, July 05, 2001 05:15 PM<!--webbot bot="Timestamp" i-CheckSum="5835" endspan -->
19 </font></p>
20 <p>Revision Status</p>
21 <table border="1" width="80%">
22 karl 1.1 <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 <td width="25%"> </td>
36 <td width="25%"> </td>
37 <td width="25%"> </td>
38 <td width="25%"> </td>
39 </tr>
40 <tr>
41 <td width="25%"> </td>
42 <td width="25%"> </td>
43 karl 1.1 <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 <p>NOTE: This is a draft copy for comment.</p>
60
61 <h2>Coding Conventions</h2>
62 <OL>
63 <LI><b>Indenting Code</b> - Indent by increments of 4 characters (with tabsize of
64 karl 1.1 8). ??? Using Tabs???.
65
66 <LI><b>Naming Conventions</b> - <font face="Courier New"> ThisIsAClassName</font> - no underscores.
67 <font face="Courier New">
68 thisIsAMethodName()</font> - no underscores.
69
70 Files Names should take advantage of case and avoid underscores.
71 Files should have the same name as the class (and same case).
72 <br>Prepend '_' to private members (including methods).
73 <LI><b>Code Line Length</b> - Lines should not span more than 80 columns.
74 When methods span more than 80 columns, do this:
75 <pre>
76 void MyClass::myMethod(
77
78 const char* someReallyLongName,
79
80 const char* someOtherReallyLongName);
81 </pre>
82 <LI> Use "char* x" rather than "char *x".
83 <LI><b>Use of <font face="Courier New">const</font></b>. Use const whenever possible.
84 Use const methods whenever possible.
85 karl 1.1 <LI><b>Braces</b> - Put opening brace on a line by itself. Braces must be aligned with control keyword:
86 <pre>
87 for(...)
88 {
89 ....
90 }
91 </pre>
92 Not this:
93 <pre> for (...)
94 {
95 ....
96 }
97 </pre>
98 <LI><b>Using Space</b> - No spaces after names.
99 <br>Separate functions with blank lines.
100 <pre> class X
101 {
102 public:
103 void f();
104 void g();
105 };</pre>
106 karl 1.1 <p>
107
108 <LI> Not "void f ()" but "void f()".
109
110 <LI>Avoid this:<br>
111 <font face="Courier New">
112 callingMyFunction(blah,<br>
113 blah2,<br>
114 blah3);</font><br>
115 Do this:<br>
116 <font face="Courier New">callingMyFunction(<br>
117 blah,<br>
118 blah2,<br>
119 blah3);</font>>/pre><br>
120 <LI>
121 <pre>Avoid this:
122 </pre>
123 <pre>
124 int x;
125 float y;
126 </pre>
127 karl 1.1 <LI>Use 0 and not NULL.
128 <li>Don't separate return type onto its own line:
129
130 Avoid this:
131 <pre>
132 int
133 f()
134 {
135 ....
136 }
137 </pre>
138
139 <li><b>Comments</b> - Use /** */ rather than /// for DOC++.
140
141 <li><b>Conditional Compilation </b>- Avoid use of conditional compilation for obscuring platrform
142 differences. Use (or put) routines in appropriate platform files
143 or in the System*.cpp files in Common.
144 </ol>
145 <h2>Testing</h2>
146
147 <p>Effective testing is essential to allowing a group to work together in a
148 karl 1.1 common code environment. We have created a structure where unit and even system
149 level tests can be created and committed to the source tree as part of all
150 development. Each major directory section includes a tests subdirectory
151 with individual directories for tests. Please create and commit tests as part of
152 the normal environment wherever it is possible. All core code should include
153 tests created in this manner as well</p>
154
155 <p>If you change code to extend it or make corrections, please review the
156 corresponding tests code to 1) add tests to cover the problem corrected 2)
157 extend tests to cover the new code added.</p>
158
159 <p>Be mindful that the tests must run on all supported platforms and
160 that a commit may break another platform.</p>
161
162 <p>Tests must clean up the effect they have on the repository.</p>
163
164 Changes must work on all platforms. Commits must not break any
165 platform.
166
167 Always write a regression test for everything.
168 <p>No warnings should be committed.
169 karl 1.1
170 Test big changes on at least Windows and Unix (or Linux)
171
172 <h2>Committing Code to CVS</h2>
173
174 <p>Don't commit anything that breaks the build (try a clean slate
175 checkout and build). Remember that if the build is broken for you, it
176 is also broken for everybody that gets the new code.</p>
177
178 <p>Always build and run all regression tests before committing. </p>
179
180 <p>No binaries may be committed to repository. </p>
181
182 <p> There are a few exceptions to this rule but binary files cause problems</p>
183
184 <h2>Using Outside Code and Libraries</h2>
185
186 <p>This is an opensource project. All code that is contributed to this
187 project must be open source and must be made available under the standard
188 license used by the Pegasus project. Do not use any outside libraries that do
189 not meet this criteria. Further, every reference to outside code make it
190 karl 1.1 more complex for others to build and work with the project and introduces
191 potential portability problems. At the same time, there may be real
192 reasons to use outside code and libraries at times. Thus, for example, the
193 initial project used the ACE_wrappers libraries extensively but with the
194 objective of eventually providing a replacement. That replacement has been
195 produced, partly because ACE was not available on all of the platforms</p>
196
197 <h2>Using Make</h2>
198
199 <p>The Pegasus project has developed a consistent and portable make system that
200 allows bot localized and global builds on a wide variety of systems from Windows
201 to Unix to the tandem platforms today. This is based on 1) using the GNU
202 Make tool as the core of the make system, 2) minimining the use of other tools.
203 </p>
204
205 <p><<EXPLAIN THE MAKE SYSTEM OR REFERENCE DOC>>>
206 </p>
207
208 <p>All code must be reachable (built) from master makefile. Otherwise it will not be reached when doing mass substitutions, testings of
209 builds, and license changes.
210 </p>
211 karl 1.1
212 <h2>DOCUMENTING
213 </h2>
214
215 <p><<<THIS SECTION NEED TO BE COMPLETED>>>
216 </p>
217
218 <h2>The Source Tree Structure</h2>
219
220 <p>We work from a single source tree in CVS. We have a fixed structure for
221 this structure.</p>
222
223 <p><<<THIS SECTION IS TBD>>></p>
224
225 <p> </p>
226
227 <p> </p>
228
229 <p>---END OF DOCUMENT--</p>
230
231 </body>
232 karl 1.1
233 </html>
|
Return to
PegasusProgrammingGuidelines.htm
CVS log
Up to [Pegasus] / pegasus / doc / WorkPapers