Editing Style Guide - FilterMeisterWiki

When saving, enter the following:

##   ##                    ZZ  Z  Z  ##   ## 
##   ##           |\     /|ZZ  Z  Z  ##   ## 
##   ##    ####   | )   ( |ZZ ZZZ Z  ##   ## 
##   ##   ##  ##  | |   | |ZZ ZZZ Z  ##   ## 
##   ##   ##  ##  | |   | |ZZ ZZZ Z  ##   ## 
 ## ##    ##  ##  | |   | | ZZ ZZZ   ##   ## 
  ###      ####   | (___) | ZZ  ZZ    #####  
             ###  (_______)

Visit Preferences to set your user name

*I have my own coding style which is heavily based on the style used in http://www.boost.org and similar high-quality C++ code, I hereby present it as a few examples and guidelines. Please comment and change so we'll end up with a useful 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 [http://www.m-w.com/dictionary 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 [http://www.m-w.com/dictionary/boolean 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 [http://alt-usage-english.org/excerpts/fxdiffer.html 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 [http://www.merriam-webster.com/dictionary/kudos 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 [http://www.m-w.com/dictionary/occurred 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 [http://www.m-w.com/dictionary/plugin 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 [http://www.m-w.com/dictionary/preferred Merriam-Webster].  Also: '''preferring''', but '''preference''' and '''prefers'''.

* '''principle''' and '''principal'''. [http://www.merriam-webster.com/dictionary/principle 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'''. [http://www.m-w.com/dictionary/publicly 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 [http://www.m-w.com/dictionary/usage Merriam-Webster]. However, either '''usable''' or '''useable''' is acceptable per [http://www.m-w.com/dictionary/useable 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>

Summary of change:
Add document to category: