Path of Exile Wiki:Manual of Style

From Path of Exile Wiki
Revision as of 22:14, 29 July 2016 by >OmegaK2 (→‎Modules: added some guidelines for modules)
Jump to navigation Jump to search

This is draft, discuss it on the talk page

Semantic Mediawiki

Properties

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


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)

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)

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 ''
-- 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


Retrieved from "https://www.poewiki.net/index.php?title=Path_of_Exile_Wiki:Manual_of_Style&oldid=840449"