History of Style Guide

**Is this intended as a general FM coding style-guide, or for the FM coding team? My own coding style is quite different, but is derived from a Java heritage. Since I'm neither part of FMDEV or a professional C/C++ developer I probably shouldn't comment here :] - Syne

***It means to serve as a style guide for the code within the documentation and possibly as a helping hand towards others. Java and C/C++ aren't much different so please comment so we could decide on which way to go. I'm no expert either (my current style is basically "stolen" from real professionals) but I'd just like a common style for docs/examples. - Martijn

----

= Spelling =

<code>

</code>

:Correct spelling is as much to be admired in source code comments and software documentation as in any highly literary work. A spell-checker can be very helpful when checking text documents, but is often less useful for vetting comments buried within cryptic source code lines (without proper tools, of course). So please take extra time and care to review your source code for correct spelling and grammar. You might even turn up a few program bugs along the way -- it has happened to me!

<code>

</code>

:The following spelling rules and suggestions are based on American, not British, usage. Since many of our European members are more familiar with British English, we won't harp on "color" versus "colour" here and there. It's more important simply to keep the usage consistent within a single document. I've used the [Merriam-Webster Online Dictionary] (an abridged work) as my primary source of reference to resolve spelling issues for the principal reason that it tends to agree with me more often than does, say, the American Heritage Dictionary.

<code>

</code>

:Most of the examples below were gathered from actual occurrences in FilterMeister documentation, postings, and code listings. If you have your own personal "pet peeves", please add them here! -Alex

<code>

</code>

* a lot, not alot. But distinguish from the verb allot.

* abbreviate, not abreviate.

* acknowledgment or acknowledgement, but acknowledgment is preferred in American English. Ditto judgment versus judgement.

* all right, not alright. But already and all ready are okay when correctly used.

* backward or backwards. A slight preference for backward as an adverb, but always backward as an adjective. Ditto for forward, downward, upward, westward, and toward.

* beveler, beveled and beveling. Also British beveller, bevelled and bevelling.

* Boolean, not boolean. Named after George Boole, "Boolean" should be capitalized per [Merriam-Webster]. However, the FM type keyword (bool)? is lowercase. Go figure.

* category, not catagory.

* compatible and compatibility, not compatable or compatability.

* definite, not definate.

* different from, different than, different to. This is a matter of usage, not spelling. According to [various sources], "different to" is used chiefly in British speech, while "different than" is chiefly American usage. The most widely accepted usage is "different from", which we hereby recommend.

* disastrous, not disasterous.

* discriminate, not descriminate.

* duplicate, not dublicate.

* e.g. and i.e., not eg or ie. These are abbreviations of exempli gratia and id est, resp., and require periods.

* Filter Factory, not FilterFactory. Two words, per Adobe.

* FilterMeister, not Filtermeister or Filter Meister, and certainly not FilterMiester! "FilterMeister™" is (or will become) a trademark, and should be spelled exactly this way (one word, camel-case). The single word form "FilterMeister" also works better in search engines (fewer spurious hits) than the two word phrase "Filter Meister".

* formatted, not formated.

* gauge, not guage. gage is also allowed, but not preferred.

* gray or grey. American English slightly prefers gray and Microsoft uses this spelling in its technical documentation and API names, so let's prefer gray in this context.

* height, not heighth or heigth.

* its versus it's, your versus you're, etc. These and many other possessive/contraction homonym pairs are easily mistyped without careful proofreading.

* kudos, not kudo. Per [Merriam-Webster], kudos is a singular word in Greek.

* label, not lable. Also labeler, labeled and labeling (or British labelled and labelling).

* license or licence. American English prefers the former.

* millennium, not millenium.

* misspell, not mispell. Something oddly recursive about this one.

* (NULL)? versus (NUL)?. "NULL" is a zero-valued pointer to nothing. "NUL" is a zero-valued character constant ('\0').

* occasion, not ocassion.

* occurred, not occured. Per [Merriam-Webster]. Also: occurring, occurrence, but occurs.

* Paint Shop Pro, not PaintShop Pro or Paintshop pro. "Paint Shop Pro®" is a registered trademark of Corel®.

* Photoshop, not PhotoShop or Photo Shop. "Photoshop™" is trademarked by Adobe.

* plug-in, not plugin. Per [Merriam-Webster] for both adjective and noun usages. But note: plug in when used as a verb.

* precede, not preceed. But succeed and supersede.

* preferred, not prefered. Per [Merriam-Webster]. Also: preferring, but preference and prefers.

* principle and principal. [Merriam-Webster] says: Although nearly every handbook and many dictionaries warn against confusing principle and principal, many people still do. Principle is only a noun; principal is both adjective and noun.

* privilege, not priviledge or privelege.

* propagate, not propogate (my personal nemesis -Alex). Ditto propaganda, not propoganda. But note propose and proponent.

* publicly or publically. [Merriam-Webster] permits either, but prefers publicly.

* recommend, not reccommend.

* resource, not ressource.

* separate, not seperate.

* their, there, they're. Another set of homonyms which are easily confused when typing rapidly.

* threshold, not threshhold or treshold. Who would have guessed?

* tileable, not tilable. Not in most dictionaries, but Google lists 18,500 hits on "tilable" versus 107,000+ hits on "tileable". Also, if you search Google for "tilable" it asks "Did you mean: tileable". 'Nuff said.

* usage, not useage. Per [Merriam-Webster]. However, either usable or useable is acceptable per [Merriam-Webster]. Enough to tear one's hair out.

* weird, not wierd. An egregious exception to the rule: [i] before [e] except after ?.

= Information =

Describe how the information stuff should be formatted.

= Controls =

Describe how the control definitions should be formatted.

= Code =

== Expressions ==

*Keep one expression on one line; each line should contain only one ; symbol. The only exception being the for statement.

== Parentheses ==

*Use spaces on the inside of parentheses; this is practically required to do decent Boolean expression formatting and should thus be used everywhere for consistency. (I disagree. -Alex.)

== Brackets ==

*Only use brackets when necessary, not for single lines of code. Commonly it is advised to always use brackets but most of the time this is ridiculous and only causes bloated source files. (I disagree. -Alex., Strongly disagree. -Martijn.)

*Place brackets on their own lines always, never combined with anything else, this makes for easy recognition.

<code>

ForEveryTile():

if( ctl( 0 ) )

Info( "Control 0 is set" );

else

{

Info( "Control 0 is not set" );

return false;

}

</code>

== Boolean expressions ==

*Split logical expressions over multiple lines whenever they concern independent variables.

*Let the code layout represent the logical structure of the expression.

*Never compare Booleans to true or false explicitly; this makes code more intuitive to read.

*Use parentheses whenever and only when mixing comparable operators such as Boolean operators, comparison operators or mathematical operators.

<code>

// Bad

if(((x>10) && (x<2+4*5)) || ((y==0) && do_first_row))

// ...

// Good

if( ( x > 10 && x < 2 + ( 4 * 5 ) )

|| ( y == 0

&& do_first_row ) )

// ...

</code>

== Indenting ==

*Use a tab size of 4 characters; any smaller will clash with logical expressions, any more is useless.

== Ternary operator ==

*Use a ternary operator whenever an if..else would normally be used which only assigns value to a single variable.

*Split the ternary operator over two lines. (I disagree. -Alex.)

*Use direct assignment of Boolean values whenever possible.

<code>

// Bad

if( a > 10 )

b = true;

else

b = false;

// Better

b = a > 10? true

: false;

// Best (because we assign Boolean values)

b = a > 10;

</code>

== Variable names ==

There are several options available and decisions to be made:

*Capitals

*Underscores

*Abbreviation

*Structuring

*Type

When combined, there are a few common standards in the C/C++ world:

*Hungarian/Microsoft notation. This is the one we encounter in the Windows API. It uses Capitals for each word and prepends the first letter of each structure level before the word describing the variable.

**width of the size of a circle: csWidth.

**Uses no underscores, has no notion of type, practically never abbreviates but is highly structured.

**Quite unreadable and likely to be quite ambiguous, structuring has practically no use in FM.

*OpenGL-like notation. This is basically caps for all words and only one underscore before the type identifier.

**width of the size of a circle: CircleSizeWidth_f (assuming floating point)

**Long names, using type can be quite redundant and long names :)

**Forces you to know the type which is a good thing.

*C++ style notation. Using no caps anywhere, underscores to separate words.

**width of the size of a circle: circle_size_width

**Long names but at least it's easy and pleasant to read.

**Has my vote - Martijn

Then there's the leading underscore thing. Some consider these to be reserved for the compiler, others (including me) like them to distinguish between normal variables and those passed in as arguments. FM has no user-defined functions yet so this issue is of no hurry.

== Efficiency ==

*Use prefix increment and decrement whenever possible instead of postfix; postfix causes a temporary variable to be created which is practically never needed. (Not necessarily true, depends on how well the compiler optimizes. -Alex.)

*Place the most discriminating (failing) Boolean expressions first; any consecutive expressions will only be tested if it evaluates to true.

<code>

// Bad

if( x > 0

&& y == 1 )

// ...

// Good

if( y == 1

&& x > 0 )

</code>