Styling Guide and Best Practices for Studio 7

Introduction

Reasons to have a styling guide in place:

• We will have hundreds of files by the end of sprint 4
• Faster to find files
• Easier to infer meaning from others' code
• Easier to diagnose issues in others' code
• Ensures new code follows the same structural/conceptual practices used already
• We become better at determining merge conflict solutions

File structuring

Files found in source/core/assets/

Structural and naming guidelines for assets

• Assets are named using "snake_case". This is to separate them from Java src files that use "PascalCase".
  • "RETROACTIVE.png" is incorrect
  • "retroactive.png" is the most correct
  • "boxBoy.png" is incorrect
  • "box_boy.png" is the most correct

Character images

• Character sprites should have their own folder under assets/images/characters/*. If a character atlas falls into a set of alternative, similar atlases, its members should have a 2-digit suffix, starting at 00.

  • "boy0.atlas" is incorrect
  • "boy_0.atlas" is also incorrect
  • "boy_00.atlas" is the most correct

  *: this is due to the sheer number of (likely unnecessary) character files in main. If less are used, then they could share images/characters/ instead.

Object images

• Assets used for rendering objects (e.g. bed, door, tree, tv) should have their own folder under assets/images/objects/**. If an object atlas falls into a set of alternative, similar atlases, its members should have a 2-digit numerical suffix, starting at 00.

  **: we can accept all object files sharing the same objects/ directory if the majority prefers it to excessive structuring

Orientation and animations

• Describing assets with their orientation should be done using North, South, East and/or West. Animations should use "ing" verbs where applicable. Files part of the same animation should have a 1-digit suffix, starting at 0. This convention is the same for declaring animations in .atlas files.

  • "boy_01_stand_up.png" is incorrect

  • "boy_01_stand_north.png" is correct if the context prefers "stand" over "standing"

  • "boy_01_standing_north.png" is the most correct when describing animations

  • For complex directions, "boy_01_standing_north_east.png" is almost correct

  • "boy_01_standing_northeast.png" is the most correct

  • For animation files of the same animation, "boy_01_standing_north_00.png" is almost correct

  • "boy_01_standing_north_0.png" is the most correct

Tile images

• Assets relating to tile textures should fall into assets/images/tiles under one of hex/, iso/, or ortho/. Such files should be prefixed with the folder they fall under.
  • "Why not separate tiles by 'grass' or 'wall' instead?" That structure would leave giant tilesets like tiles/ortho/ortho_terrain_set.png in a weird position.
  • "ortho/terrain_set.png" is not correct. In a larger context, this can get confusing if you used that and "hex/terrain_set.png", but internally refer to both as "terrain_set.png"
  • "ortho/ortho_terrain_set.png" is the most correct

UI images

• Assets loaded specifically for UIComponents should have their own folder under assets/images/ui/.

Files found in source/core/src/main/

Structural and naming guidelines for Java files in src

• All classes extending Component should be packaged alongside the classes that implement them, inside their own components/ folder.

  • Components commonly used in classes extending Entity can be found in src/.../entities/components/, for example.
  • Exceptions to this rule include: src/.../screens
    • One screen usually has many unique UIComponents, so it is cleaner to have them packaged alongside each other instead of src/.../screens/components holding so many unique components.

• Components that are used in more than one type of class should fall into a higher-level package, such as src/.../physics/components/

  • These components usually just their own package by having a lot of non-Components falling nicely into src/.../physics/. If not, they should fall under src/.../generic/
  • Exceptions to this rule could include components that are HEAVILY associated with one class, but is used occasionally elsewhere

• UIComponents should be suffixed with "Display". When viewing the file structure, this makes it easier to separate mostly-functional components from mostly-aesthetic ones.

Files found in source/core/src/test/

Test packages should follow the exact same structure as src/main/com/deco2800/game/. This will take care of protected variables being unusable otherwise.

Symbol declarations in .java files

Constants and Enumerations

As standard in Java, constants and enumerations follow "UPPER_SNAKE_CASE"

• e.g. ROOT_DIR, SETTINGS_FILE, WINDOW_WIDTH, WINDOW_HEIGHT

Variables

As standard in Java, variables follow "camelCase"

• e.g. logger, game, mainMenuTextures

Functions

As standard in Java, functions follow "camelCase"

• e.g. create(), earlyUpdate(), getEntity()
• Constructors following "PascalCase" are an exception due to naming conventions in Java

Event names using the existing event system

Not standardised anywhere, but events should use "snake_case"

• e.g. start, change_character, win_default, walking_north

Why??

• Avoids navigation issues where events could share the same prefix/name as other variables or functions. It is much easier to find/replace all events if they follow this structure and avoids accidents like replacing function names.
  • This is especially useful for atlases that already follow "snake_case" for referencing .png files and declaring animations. A simple search for the term "walking_north" will bring up instances in atlases and event names.
• Event names are closer to constants/enumerations than they are to standard variables. Using underscores is more appropriate for this reason. There is an argument for event names using "UPPER_SNAKE_CASE" but again, using "lower_snake_case" avoids navigational confusion with constants/enums.

Standard and Best Practices

Unique entity components

Every entity should encapsulate its unique functionality inside a "[Prefix]Actions" component and an optional "[Prefix]Display" component.

"Action" components will typically extend InteractionComponent if the entity should be interactable, otherwise Component. Every entity should have exactly one of these. More information on how to use Interactions can be found here.

"Display" components will typically extend UIComponent to receive UI functionality. These components are reserved for entities that should render things to the screen.