Merge pull request #79 from CorruptComputer/patch-1

Update best_practices.adoc

src/docs/asciidoc/jme3/intermediate/best_practices.adoc

@@ -1,7 +1,7 @@
 = Best Practices For jME3 Developers
 :author: 
 :revnumber: 
-:revdate: 2016/03/17 20:48
+:revdate: 2017/11/26 13:30
 :relfileprefix: ../../
 :imagesdir: ../..
 ifdef::env-github,env-browser[:outfilesuffix: .adoc]
@@ -9,7 +9,7 @@ ifdef::env-github,env-browser[:outfilesuffix: .adoc]
 
 Every milestone of a game development project is made up of phases: Planning, development, testing, and release. Every milestone involves updates to multi-media assets and to code.  
 
-This “best practices page is a collection of recommendations and expert tips. Feel free to add your own!
+This "best practices" page is a collection of recommendations and expert tips. Feel free to add your own!
 
 
 == Requirements and Planning
@@ -23,7 +23,7 @@ As a quick overview, answer yourself the following questions:
 
 *  Motivation
 **  Sum up your game idea in one catchy sentence. If you can't, it's too complicated. +
-E.g. “Craft by day, fight by night!
+Exmple: "Craft by day, fight by night!"
 **  Who's the target group? Are you making it for your friends or are you trying to attract the masses?
 
 *  Game type
@@ -35,13 +35,13 @@ E.g. “Craft by day, fight by night!
 *  Gameplay
 **  What is the start state, what is the end state? (if applicable)
 **  What resources does the player manage? How are resources gained, transformed, spent? +
-E.g. “points, health, speed, gold, xp, mana.
+Exmple: points, health, speed, gold, xp, mana.
 **  How does the player interact? Define rules, challenges, game mechanics.
 **  What state is considered winning, and what losing, or is it an open world?
 
 *  Multi-media assets
 **  Which media will you need? How will you get this content? +
-E.g. models, terrains; materials, textures; noises, music, voices; video, cutscenes; spoken/written dialog; level maps, quests, story; AI scripts.
+Exmple: models, terrains; materials, textures; noises, music, voices; video, cutscenes; spoken/written dialog; level maps, quests, story; AI scripts.
 
 *  Interface
 **  Can you achieve a high degree of input control? (Even minor navigation and interaction glitches make the game unsolvable.)
@@ -58,18 +58,18 @@ Use an link:http://en.wikipedia.org/wiki/Issue_tracking_system[issue and bug tra
 **  Artwork: Test asset loading and saving with mock-ups and stock art.
 **  Lay out the overall application flow, i.e. switching between intro / options / game screen, etc.
 **  Get one typical level working before you can announce the Alpha Release. +
-E.g. if the game is a “Jump'n'Run, jumping and running must work.
+Exmple: if the game is a "Jump'n'Run", jumping and running must work.
 
 .  Alpha Release
 .  Pre-Beta Development
 **  Artwork: Replace all mock-ups with first drafts of real media and level maps.
-**  Have your team members review and “alpha test it on various systems, track bugs, debug, optimize.
+**  Have your team members review and alpha test it on various systems, track bugs, debug, optimize.
 **  Declare link:http://en.wikipedia.org/wiki/Feature_freeze[Feature Freeze] before you announce the Beta Release to prevent a bottomless pit of new bugs.
 
 .  Beta Release
 .  Post-Beta Development
 **  Artwork: Fill in the final media and level maps.
-**  Have external people review and “beta test it, make it easy to report bugs.
+**  Have external people review and beta test it, make it easy to report bugs.
 **  Fix high-priority bugs, even out the kinks in code and gameplay, don't add new features for now!
 
 .  Gamma Release, Delta Release… = Release Candidates
@@ -78,17 +78,17 @@ E.g. if the game is a “Jump'n'Run, jumping and running must work.
 
 .  Omega = Final Release
 
-How you name or number these stages is fully up to your team. Development teams use numbered milestones (m1, m2, m3), Greek letters (e.g. alpha, beta, gamma, delta), link:http://en.wikipedia.org/wiki/Software_versioning["major.minor.patch-build" version] numbering (e.g. “2.7.23-1328), or combinations thereof. 
+How you name or number these stages is fully up to your team. Development teams use numbered milestones (m1, m2, m3), Greek letters (ex. alpha, beta, gamma, delta), link:http://en.wikipedia.org/wiki/Software_versioning["major.minor.patch-build" version] numbering (ex. "2.7.23-1328"), or combinations thereof. 
 
 
 === Use File Version Control
 
 Whether you work in a team or alone, keeping a version controlled repository of your code will help you roll-back buggy changes, or recover old code that someone deleted and that is now needed again.
 
-*  Treat commit messages as messages to your future self. “Made some changes is _not_ a commit message.
+*  Treat commit messages as messages to your future self. "Made some changes" is _not_ a commit message.
 *  The jMonkeyEngine SDK supports Subversion, Mercurial, and Git. +
 If you don't know which to choose, Subversion is a good choice for starters.
-*  Set up your own local server, or get free remote hosting space from various open-source dev portals like link:http://sourceforge.net/[Sourceforge], link:https://github.com/[Github], link:https://bitbucket.org/[bitbucket] (supports private projects), link:http://home.java.net/create-project[Java.net]…
+*  Set up your own local server, or get free remote hosting space from various open-source dev portals like link:http://sourceforge.net/[SourceForge], link:https://github.com/[GitHub], link:https://bitbucket.org/[BitBucket] (supports private projects), link:https://about.gitlab.com/[GitLab] (free private projects)…
 
 
 == Multi-Media Asset Pipeline
@@ -126,8 +126,8 @@ Learn details about the <<jme3/intermediate/multi-media_asset_pipeline#,Multi-Me
 
 [NOTE]
 ====
-Many game developers dream of creating their very own “MMORPG with full-physics, AI, post-rendering effects, multi-player networking, procedurally generated maps, and customizable characters. So why aren't there tons of MMORPGs out there? +
-Even for large experienced game producers, the creation of such a complex game is time-intensive and failure-prone. How familiar are you with multi-threading, persistence, optimization, client-server synchonization, …? Unless your answer is “very!, then start with a single-player desktop game, and work your way up – just as the pros did when they started.
+Many game developers dream of creating their very own MMORPG with full-physics, AI, post-rendering effects, multi-player networking, procedurally generated maps, and customizable characters. So why aren't there tons of MMORPGs out there? +
+Even for large experienced game producers, the creation of such a complex game is time-intensive and failure-prone. How familiar are you with multi-threading, persistence, optimization, client-server synchonization, …? Unless your answer is "very!", then start with a single-player desktop game, and work your way up – just as the pros did when they started.
 ====
 
 
@@ -139,7 +139,7 @@ Every jME3 game is centered around one main class that (directly or indirectly)
 
 [IMPORTANT]
 ====
-Note that although the “SimpleApplication name might be misleading, all jME3 applications, including very large projects, are based on this class. The name only implies that this class itself is a simple application already. You make it “non-simple by extending it!
+Note that although the "SimpleApplication" name might be misleading, all jME3 applications, including very large projects, are based on this class. The name only implies that this class itself is a simple application already. You make it "non-simple" by extending it!
 ====
 
 
@@ -160,14 +160,14 @@ You have a list of features that you want in game, but which one do you implemen
 
 .  Make sure the game's high-level frame (screen switching, network sync, loading/saving) is sound and solid. 
 .  Start with implementing the most complex game feature first – the one that imposes most constraints on the structure of your project (for example: multi-player networking, or physics.)
-.  Add only one larger feature at a time. If there are complex interactions (such as “networking + physics), start with a small test case (“one shared cube) and work your way up. Starting with a whole scene introduces too many extra sources of error.
+.  Add only one larger feature at a time. If there are complex interactions (such as networking + physics), start with a small test case (one shared cube) and work your way up. Starting with a whole scene introduces too many extra sources of error.
 .  Implement low-complexity decorations (audio and visual effects) last.
 .  Test for side-effects on existing code after you add a new feature (regression test).
 
 
 [TIP]
 ====
-Acknowledge whether you want a feature because it is necessary for gameplay, or simply because “everyone else has it. Your goal should be to bring out the essence of your game idea. Don't water down gameplay by attempting to make it “do everything, but better. Successful high-performance games are the ones where someone made smart decisions what to keep and what to _drop_.
+Acknowledge whether you want a feature because it is necessary for gameplay, or simply because "everyone else has it". Your goal should be to bring out the essence of your game idea. Don't water down gameplay by attempting to make it "do everything, but better". Successful high-performance games are the ones where someone made smart decisions what to keep and what to _drop_.
 ====
 
 
@@ -179,13 +179,13 @@ Acknowledge whether you want a feature because it is necessary for gameplay, or
 ====
 *Avoid the Anti-Pattern:* Don't design complex role-based classes using Java inheritance, it will result in an unmaintainable mess. +
 Example: You start extending `Node` –> `MyMobileNode` –> `MyNPC`. Then you extend `MyFighterNPC` (defends, attacks) and `MyShopKeeperNPC` (trades) from `MyNPC`. What if you need an NPC that trades and defends itself, but doesn't attack? Do you extend MyShopKeeperNPC and copy and paste the defensive methods from MyFighterNPC? Or do you extend MyFighterNPC and override the attacking methods of its parent? Neither is a clean solution. +
-Wouldn't it be better if behaviours were a separate “system, and attributes were separate “components that you add to the “entity that needs them?
+Wouldn't it be better if behaviours were a separate system, and attributes were separate components that you add to the entity that needs them?
 ====
 
 
 You write Java classes named `Controls` to implement your Game Entities, and define an Entity's visuals, attributes, and behaviours. In jME, `Spatial`s (`Nodes` or `Geometry`s) are the visual representation of the game entity in the scene graph.
 
-*  Game entities have *attributes* – All Entities are neutral _things_, only their attributes define what an entity actually _is_ (a person or a brick). In jME, we call these class fields of Spatials “user data. +
+*  Game entities have *attributes* – All Entities are neutral _things_, only their attributes define what an entity actually _is_ (a person or a brick). In jME, we call these class fields of Spatials "user data". +
 Example: Players have *class fields* for `id, health, coins, inventory, equipment, profession`.
 *  Game entities have *behaviours* – Behaviour systems communicate about the game state and modify attributes. In jME, these game mechanics are implemented in modular `update()` methods that all hook into the main update loop. +
 Example: Players have *methods* such as `walk(), addGold(), getHealth(), pickUpItem(), dropItem(), useItem(), attack()`.
@@ -193,14 +193,14 @@ Example: Players have *methods* such as `walk(), addGold(), getHealth(), pickUpI
 
 [TIP]
 ====
-*Follow the Best Practice:* In general, use composition over inheritance and keep “what an entity does (behaviour system) separate from “what this entity is (attributes).
+*Follow the Best Practice:* In general, use composition over inheritance and keep what an entity does (behaviour system) separate from what this entity is (attributes).
 
 *  Use `<<jme3/advanced/spatial#,setUserData()>>` to add custom attributes to Spatials.
 *  Use <<jme3/advanced/custom_controls#,Controls>> and <<jme3/advanced/application_states#,Application States>> to define custom behaviour systems.
 ====
 
 
-If your game is even more complex, you may want to learn about “real Entity Systems, which form a quite different programming paradigm from object oriented coding but are scalable to very large proportions. Note however that this topic is very unintuitive to handle for an OOP programmer and you should really decide on a case basis if you really need this or not and gather some experiences before diving head first into a MMO project emoji:smiley
+If your game is even more complex, you may want to learn about "real" Entity Systems, which form a quite different programming paradigm from object oriented coding but are scalable to very large proportions. Note however that this topic is very unintuitive to handle for an OOP programmer and you should really decide on a case basis if you really need this or not and gather some experiences before diving head first into a MMO project emoji:smiley
 
 *  link:http://cowboyprogramming.com/2007/01/05/evolve-your-heirachy/[http://cowboyprogramming.com/2007/01/05/evolve-your-heirachy/] 
 *  link:http://www.gamasutra.com/blogs/MeganFox/20101208/88590/Game_Engines_101_The_EntityComponent_Model.php[http://www.gamasutra.com/blogs/MeganFox/20101208/88590/Game_Engines_101_The_EntityComponent_Model.php]
@@ -286,7 +286,7 @@ It's unlikely you will fully document _every_ class you write, we hear you. Howe
 *  Write down implicit limits (e.g. min/max values) and defaults while you still remember.
 *  In which situation do I want to use this, is this part of a larger process? Is this step required, or what are the alternatives? 
 
-Treat javadoc as messages to your future self. “genNextVal() generates the next value and “@param float factor A factor influencing the result do _not_ count as documentation.
+Treat javadoc as messages to your future self. `genNextVal() generates the next value` and `@param float factor A factor influencing the result` do _not_ count as documentation.
 
 
 == Debugging and Test Phase