00001
00002
00003
00004
00005
00006
00007
00008
00009
00010
00011
00012
00013
00014
00015
00016
00017
00018
00019
00020
00021
00022
00023
00024
00025
00026
00027
00028
00029
00030
00031
00032
00033
00034
00035
00036
00037
00038
00039
00040
00041
00042
00138
00139
00140
00141
00178
00179
00180
00181
00249
00250
00251
00252
00359
00360
00361
00362
00484
00485
00486
00487
00588
00589
00590
00591
00611
00612
00613
00614
00722
00723
00724
00725
00861
00862
00863
00864
00921
00922
00923
00924
00962
00963
00964
00965
01219 }
01220
01221 if (((a == b) && (c < d)) || (e == f))
01222 {
01223
01224 }
01225 </pre>
01226 <li>The block of any <code>if</code> statement should always follow on
01227 a separate line.
01228 <PRE>
01229 if ( ) i++;
01230
01231 if ( )
01232 i++;
01233 </PRE>
01234 <li>Braces ("{}") which enclose a block should be aligned as follows:
01235 <PRE>
01236 if ( )
01237 {
01238 i++;
01239 j++;
01240 }
01241
01242 if ( ) {
01243 i++;
01244 j++;
01245 }
01246
01247 if ( )
01248 {
01249 i++;
01250 j++;
01251 }
01252 </PRE>
01253
01254 Adding the following line to your \c .emacs file will help:
01255
01256 <PRE>
01257 (c-set-offset 'substatement-open 0)
01258 </PRE>
01259
01260 </ul>
01261
01262
01263 <h5>Miscellaneous</h5>
01264 <UL>
01265 <li>Always provide a space on both sides of <code>=</code> signs and all logical
01266 operators.
01267 <br>
01268 <li>Each statement shall always be in a separate line, however small it may appear.
01269 <br>
01270
01271 <Li>Do not use <EM>spaces</EM> around
01272 `<CODE>.</CODE>' or `<CODE>-></CODE>', nor between unary operators
01273 and operands.
01274 <br>
01275 <li>Use the c++ mode in GNU Emacs to
01276 format code.
01277 </UL>
01278
01279 <H3>Coding Rules</H3>
01280
01281
01282 <ul>
01283 <li>A public member function must never return a non-const reference
01284 or pointer to member data.
01285 <br>
01286 <li>Constants are to be defined using <code>const</code> or
01287 <code>enum</code>; never using <code>#define</code>.
01288 <br>
01289 <li>A switch statement must always contain a default branch which
01290 handles unexpected cases.
01291 </ul>
01292
01293
01294 <H3>Output</H3>
01295
01296 The <code>NOX::Utils</code> class has utility functions related
01297 to printing. To use it, include <code>NOX_Utils.H</code>.
01298
01299 <ul>
01300 <li>For <b>any</b> non-error print statement, call the
01301 <code>NOX::Utils::out</code> or <code>NOX::Utils::pout</code> functions with the appropriate
01302 MsgType flag. The flags are:
01303 <br>
01304 <ul>
01305 <li><code>NOX::Utils::Error </code>
01306 <li><code>NOX::Utils::Warning</code>
01307 <li><code>NOX::Utils::OuterIteration</code>
01308 <li><code>NOX::Utils::InnerIteration</code>
01309 <li><code>NOX::Utils::Parameters</code>
01310 <li><code>NOX::Utils::Details</code>
01311 <li><code>NOX::Utils::OuterIterationStatusTest</code>
01312 <li><code>NOX::Utils::LinearSolverDetails</code>
01313 <li><code>NOX::Utils::TestDetails</code>
01314 <li><code>NOX::Utils::StepperIteration</code>
01315 <li><code>NOX::Utils::StepperDetails</code>
01316 <li><code>NOX::Utils::StepperParameters</code>
01317 <li><code>NOX::Utils::Debug</code>
01318 </ul>
01319
01320 </ul>
01321
01322
01323 <H3>Error Handling</H3>
01324
01325 <ul>
01326 <li>Always check return values of functions for errors.
01327 <li>In general, try to recover from errors.
01328 <li>If you must throw an exception, always print an explanation with
01329 the function name to <code>NOX::Utils::err</code> or <code>NOX::Utils::perr</code> and then throw an exception with the string
01330 <code>"NOX Error"</code>. For example if utils is a NOX::Utils object,
01331
01332 <pre>
01333 if (/* Error Condition */)
01334 {
01335 utils.err() << "ERROR: NOX::Epetra::Group::getNewton() - invalid Newton vector" << endl;
01336 throw "NOX Error";
01337 }
01338 </pre>
01339
01340 </ul>
01341
01342 <H3>Comments</H3>
01343
01344 We use Doxygen for the comments. To generate the documentation. Instructions can be found in the README file in the top-level nox directory.
01345
01346 <ul>
01347 <li> Document each class, function, and enum in the header
01348 files.
01349 <br>
01350 <ul>
01351 <li> The one exception is that functions in derived objects do not
01352 need to be documented <b>if</b> the documentation is inherited from
01353 the base class. This should be tested in Doxygen to be sure that it
01354 works correctly.
01355 <br>
01356 </ul>
01357 <li> Here's an example of documented a class. Note the formatting of
01358 the comments. It's a C-style comment. The open comment marker
01359 (<code>/*</code>) is followed by an exclamation mark to indicate that
01360 it's a Doxygen comment. The open and close comment markers are on
01361 lines by themselves, and the text of the comment is indented two
01362 spaces. Always include a <code>\brief</code> description. The long
01363 description follows. Observe the use of the formatting tags
01364 <code>\c</code> and <code>\e</code>. The <code>\note</code> tag is
01365 used for any special notes. The <code>\author</code> tag is
01366 recommended.
01367
01368 <pre>
01391 class Combo : public Test {
01392 ...
01393 };
01394 </pre>
01395
01396 <li>Any parameters that are used within the class <b>must</b> be
01397 documented in the class description <b>and</b> in the file NOX_Description.H on the parameters "page".
01398 Note that the name, a brief description, and the default value for
01399 each parameter is listed.
01400 <pre>
01432 </pre>
01433 Here's a more complicated example to produce a two-tiered list.
01434 <pre>
01449 </pre>
01450
01451
01452 <li>Constants and enums can generally be described with simple
01453 <code>\brief</code> comments. Those can be formatted in either of two
01454 ways, as follows.
01455
01456 <pre>
01461 enum ComboType {AND, OR};
01462
01464 Combo(ComboType t = OR);
01465 </pre>
01466
01467 <li>Doxygen does automatically cross-linking, which is very
01468 convenient. However, sometimes it cross-links when you don't intend
01469 for it to. For example, the following line would automatically
01470 generate a link from the word <code>Newton</code> to the
01471 NOX::Solver::Newton class.
01472
01473 <pre>
01475 </pre>
01476
01477 To prevent that automatic link, insert a percent sign (<code>%</code>)
01478 immediately before the word that is causing the link. For example,
01479
01480 <pre>
01482 </pre>
01483 </ul>
01484 \endhtmlonly
01485
01486 */
01487
01488 /* ************************************************************************ */
01489 /* ************************************************************************ */
01490 /* ************************************************************************ */
01491
01565 /* ************************************************************************ */
01566 /* ************************************************************************ */
01567 /* ************************************************************************ */
01568
01820 /* ************************************************************************ */
01821 /* ************************************************************************ */
01822 /* ************************************************************************ */
01823
01943 /* ************************************************************************ */
01944 /* ************************************************************************ */
01945 /* ************************************************************************ */
01946
01965 /* ************************************************************************ */
01966 /* ************************************************************************ */
01967 /* ************************************************************************ */
01968
02027 /* ************************************************************************ */
02028 /* ************************************************************************ */
02029 /* ************************************************************************ */
02030
02328 /* ************************************************************************ */
02329 /* ************************************************************************ */
02330 /* ************************************************************************ */
02331
02332
02338 /* ************************************************************************ */
02339 /* ************************************************************************ */
02340 /* ************************************************************************ */