Talk:Nasal Style Guide

Hi Gijs.. or anyone..

Can i suggest this page is re inserted..

Particular with Recent James comments on Newgroup .. If its OK I will then format.. said pedro ;-) >>>>>

That's all a good idea, but do note that these comments are about C++ guidelines NOT Nasal, so better move this stuff to a dedicated "Core Development" style guide. Nasal is a completely different beast.--Hooray (talk) 03:50, 4 October 2013 (UTC)

Rules ?

• No, there's rules, since the codebase contains quite a mixture.
• We could start a wiki page
• only things to really care about.. (said James)

Member Vars

m_ or _ prefix for member variables

• the _ prefix is widely used but technically illegal by ISO C++
• m_ is a slight preference now

• Some prefer lowerCamelCaseWithoutUnderscores for method and variable names
• but you will find plenty of other places in the code which use all_lower_case
  • usually try to follow the style of the code you're working in/near!

fully brace conditions

• even single line!
• This one is a pain but we've had several bugs with nested ifs-without-braces being modified and introducing logic errors.
• In several cases people forgot C++ is not Python:

 if (you do this)
 if (you keep do thing)
 if (you then do this)
   printf("terrible things can happen");
 else
   printf("This is not python!");
 :)

Naming

Regarding naming, longer names and fewer comments are better. Don't do:

   double m_vXr; /// the velocity tachyon flux

better do:

   double m_velocityTachyonFlux;

Of course only people with auto-completing editors agree with this! Shorter names are fine for locals or arguments but still aim to be descriptive.

- please make a helper function for the great-circle XTK error function, with some sane name like 'greatCircleCrossTrackError'. And please include a full URL to the aviation formulary link, for future readers of the code.

- where you only want course OR distance, SGGeodesy has some convenience wrappers (I realise in most places in this patch you do want both). This is just to improve readability right now (avoids useless 'az2' declarations), but in the future we might be able to do less work if only one value is needed.

- Avoid UTF-8 degree symbols in comments, it might upset some compilers. We recently had an issue with the older GCC on Jenkins rejecting UTF-8 BOM marker.

Arithmetic

• prefer arithmetic terms in conditions to *always* be parenthesised, we've had some bad bugs due to this, so:

  if (a < (b + c))
  NOT
  if (a < b + c)

= Complex Conditions

• Where boolean conditional get complex, create explicit bools

so instead of:

   if ((some complex test) && (some other complex test) && ((another thing) || (still more))) 

More readable to do is:

   bool answerOfTest1 = some complex text
   bool answerOfTest2  = some other complexTest

   if (answerOfTest1 && answerOftest2 )

• NOTE: The compiler will get rid of the bool vars, although you might force evaluation of more terms depending on how smart you the optimiser is, but you force yourself to give each boolean expression a name, like 'isWithinOverflightDistance' or 'isWithinInterceptAngle'.
• As a result it becomes much easier for someone else to evaluate the conditional logic and decide if they agree with it or not.
• If the boolean test is used more than once, make it into a helper method

- grep-ing for methods names is*() and has*() in the codebase points to many of these.