Path of Exile Wiki:Manual of Style

This is draft, discuss it on the talk page

Editing

Style of pages

When creating new pages try to keep to the same style as other similar pages have. This helps both readers and editors, the readers gets accustomed to where they can find what they're looking for and the editors can quickly create pages by copy and pasting from other pages.

Things to try and keep similar are

• Header names and order
• Referencing style
• Navigation boxes
• Categories

If there is a substitution template available for the type of pages you're creating, it's recommended to use it:

• Area
• Item

"Character" vs "Player"

• Use "character" when describing things that arise as a result of gameplay such as attributes, damage, etc.
  • Good: "Chaos Inoculation makes the character immune to chaos damage"
  • Bad: "Chaos Inoculation makes the player immune to chaos damage"
• Use "player" when describing things related to the interface of the game
  • Good: "The player can identify an item with a Scroll of Wisdom"
  • Bad: "The character can identify an item with a Scroll of Wisdom"

Use British English

"Defence", not "Defense". "Armour", not "Armor". Where appropriate, create redirects from American English spellings to their British spellings.

Referencing

Often when you want to contribute something to a topic it is new knowledge you've recently learnt that the wiki was missing. We, the readers, would like to know as well where you got that information from to determine how reliable the statement is now. When citing sources it is common practice to include page address, author, page title, publisher, date and the date when you read the source.

To avoid clutter, use list-defined references with {{reflist}} and use {{cite web}} when citing websites.

Below is an example with the preferred style and templates:

only deals damage once, equal to the sum of calculated damage from each weapon.

Dual strike only deals damage once, equal to the sum of calculated damage from each weapon.<ref name="DualStrike" />
(...)
==References==
{{reflist|refs=
<ref name="DualStrike">{{cite web|title=Dual Strike|url=https://www.pathofexile.com/forum/view-thread/13701/filter-account-type/staff/page/2#p635984|author=Mark_GGG|date=Sep 10, 2012|accessdate=June 29, 2017|publisher=Official Path of Exile Website}}</ref>
}}

Sandbox

Sandboxes for experimental wiki editing can be created in your own userspace. Click on My User Page and create subpages from there. An example would be user:YourUserName/sandbox.

Semantic Mediawiki

To make sure tables and important numbers stays up to date automatically this wiki uses smw:Semantic Mediawiki. It is a tool that allows querying various values from other pages, similarly to how the category pages are populated. Getting comfortable with this tool does indeed take some time so don't be afraid to ask for help.

Properties

For more information about properties, see smw:Help:Properties_and_types.

Properties are the basic way of entering semantic data in Semantic MediaWiki. Properties can be viewed as «categories for values in wiki pages».

Properties should follow these rules in order to have a consistent naming scheme throughout the wiki.

Names should be short, meaningful and avoid ambiguity

This should be the case so what the property means can be identified by reading the name on sight. It should also avoid clashes with other properties.

Good:

[[Is forsaken master::Vorici]]

Bad:

[[Is:Vorici]]

Names should start with a verb

This should be done to avoid confusion about what the property actually does.

Good:

On page "Cobalt Jewel"
[[Is base item::Cobalt Jewel]]

On page "Army of Bones"
[[Has base item::Cobalt Jewel]]

Bad:

On page "Cobalt Jewel"
[[base item::Cobalt Jewel]]

On page "Army of Bones"
[[base item::Cobalt Jewel]]

Use "Is ..." for setting a single piece of information that can be used to identify the page based on the property; in particular this should be set on every page of the same "type".

See example above.

Use "Has ... " for setting additional information about the page.

Properties for multiple values should be plural; singular otherwise

The intention is to help people to tell what to expect when they are perform an ask query on a page. So properties that are intended to have multiple values (and commonly do so), should be in plural while others that have a single value associated with them should be in singular.

This rule is not strict. The use of plural naming should be considered for case there can be multiple values.

Good:

On a skill page
[[Has gem tags::Fire]]
[[Has gem tags::Cold]]
[[Has gem tags::Spell]]

Bad:

On a skill page
[[Has gem tag::Fire]]
[[Has gem tag::Cold]]
[[Has gem tag::Spell]]

Absence should be indicated by a "no"

Since it is not possible to query for the absence of properties, sometimes properties for the absence of other properties have to be created. In these cases they should be indicated by a no in their name, like so:

[[Has no ...]]

Additionally they should have Has type::Boolean set.

For example:

Property:Has item class restrictions indicates a list of restrictions

Property:Has no item class restrictions indicates the absence of said list

Result templates

• The guidelines for templates in general apply
• Create the templates with the prefix SMW
• Add the template to Category:SMW result formatting templates
• Add outro/intro templates as subpages to the main template. Document it on the /doc page if outro/intro templates are needed

Templates

General

• Always document templates on the respective /doc page (see Template documenation for details)
• Complicated templates should be implemented in lua
• Add categories to the /doc page
• Use English words for naming separated by a space
• Do not capitalize all words
• Consider creating /testcases

Template Documentation

• Always document the template you are creating
• Create a list of arguments the template takes and a description of what they do (and if they are optional)
• Add appropriate categories to the template (NOT the /doc subpage, i.e. use <includeonly></includeonly> tags)
  • For lua based templates add Template:Lua at the top

Modules

General

• Use underscore_naming for variables and functions
• Use 4 spaces for indentation
• Add extension documentation to /doc if possible, however this is not required if the code is readable
• If implementing a template in lua
  • Add to the lua comments which template(s) are implemented by the function
  • Add to the /doc page which templates are implemented
  • Add to a link from the template's /doc page using Template:Lua

Module Documenation

• Add appropriate categories to the template (NOT the /doc subpage, i.e. use <includeonly></includeonly> tags)
  • For templates for inclusion in other templates add Template:ProgrammingModule

Coding Style

Define variables as local unless they are otherwise needed

As the title suggest try to define locally in the scope they are needed.

Compress boolean statements if possible

This may be require some basic familiarity with Boolean algebra.

• Examples

  -- Bad
  not (a == b)
  -- Good
  a ~= b
  
  -- Bad
  not (a ~= b)
  -- Good
  a == b
  
  -- Bad
  a and (a or b)
  -- Good
  a
  
  -- Bad
  a or (a and b)
  -- Good
  a
  

Strings connecting

There are 3 basic rules:

• If the string is very long to connect, use a table and table.concat. This is faster and more readable

  -- Don't
  local out = ''
  out = out .. 'a'
  out = out .. 'b'
  out = out .. 'c'
  out = out .. 'd'
  out = out .. 'e'
  out = out .. 'f'
  return out
  -- Do
  local out = {}
  out[#out+1] = 'a'
  out[#out+1] = 'b'
  out[#out+1] = 'c'
  out[#out+1] = 'd'
  out[#out+1] = 'e'
  out[#out+1] = 'f'
  return table.concat(out, '')
  

• If the string is short, but has multiple arguments, use string.format, while it may be a bit slower, it is much more readable

  -- Hard to read
  "#ask:[[Is event::" .. args.type .. "]] [[Has release date::<" .. args.release_date .. "]]"
  -- Better to read
  string.format("#ask:[[Is event::%s]] [[Has release date::<%s]]", args.type, args.release_date)
  

• Use .. for other simple cases

  -- This is ok
  myvar .. other_var .. whatever
  

Avoid code duplication

Please try to avoid any form of repeated (in particular 'spaghetti') code. Minor repeats where required are, but large portions of the code repeating itself should be avoided.

Consider the following techniques:

• Use library modules to reduce code duplication
• Use poe wiki library modules like Module:Util, Module:Game to reduce code duplication
• Move code that is used regularly into a function; if the code is used...:
  • ... only used in that module, add as local, non callable function to the module
  • ... used primarily in that module, but may be used in others, add it to the return table
  • ... is generally useful for a lot of various modules consider adding it to Module:Util (discuss on talk page first)
• For formatting strings based on conditions, consider moving the formatting itself outside of the conditions if it is the same
• For long if ... elseif ... elseif ... elseif ... end that execute similar code create a table and loop trough the table