Cosmos Coding Standard
From WoWWiki
Contents |
Welcome, developers of Cosmos.
I'm putting this page up on the wiki to form style guidelines for all of us. I chose to place this on the Wiki so that we can hash out details together in a common place. I realize many of our addons do not follow Style standards, so if you wish to report them, please do so.
XML
XML Files should be formatted like:
<Ui xmlns="http://www.blizzard.com/wow/ui/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.blizzard.com/wow/ui/ ..\..\FrameXML\UI.xsd"> <!-- $Id$ --> <!-- Localization --> <Script file="localization.lua"/> <Script file="localization.de.lua"/> <Script file="localization.fr.lua"/> <!-- My Script --> <Script file="MyAddOnObject.lua"/> <!-- My AddOn Templates --> <Include file="MyAddOnFrameTemplate.xml"/> <Frame name="MyAddOnTemplate"/> <!-- My AddOn Frames --> <Frame name="MyAddOnFrame" parent="UIParent"/> <Frame name="MyAddOnFrame2" parent="SomeFrame"/> </Ui>
Frames
Frames should always use $parentSubFrame notations where-ever relevant.
Script Tags
<OnWhatever> tags should directly call a function in your lua. This is so that testing code later can be done with a single editor window.
<OnEvent> MyFileName_MyFrameType_OnEvent(event); </OnEvent>
Lua
File Header
There are two options with file headers. There are two because some editors automatically add -- to the beginning of multi-line comments and some do not.
Option A:
--[[ MyAddOn Short Description By: John F. Bar Special Thanks: Jude Law Description Text. $Id$ $Rev$ $LastChangedBy$ $Date$ ]]--
(The final two -- are not nessecary, but they look pretty )
Option B:
--[[ -- MyAddOn -- Short Description -- -- By: John F. Bar -- Special Thanks: Jude Law -- -- Description Text. -- -- $Id$ -- $Rev$ -- $LastChangedBy$ -- $Date$ --]]
In summary, file headers are short, but can contain plenty of information. The $Id$ and similar tags allow us to store information about the state of a current file.
File Organization
Lua files should be organized as:
- File Header
- Constants
- Library Functions
- Normal Functions
- Event Handlers
- Code Examples
Sections should be separated by a separator:
-------------------------------------------------- -- -- The Current Section -- --------------------------------------------------
Constants
Constants are in CAPS, along with a value
MY_TIMEOUT = 12; -- Seconds
Function Header
Function headers are a contract. They say what you will accept and what you will give back in return. However, some functions are extremely redundant and do not require a full function header. In the air of practicality, we treat them separately.
Library Functions
If a function is meant to be used by other addons or other users it is vital that their inputs and output be clear. Library functions are a type of re-usable function, which is also contained inside a namespace. E.g.
MyLibrary = {
doFunction();
};
- Library function names should always be of the format
- verbWordWordWord
Library function headers should be detailed:
Option A:
--[[
doFunction (string arg1, table arg2 [, number arg3])
does this amazing function
Args:
arg1 - the name of the frame
arg2 - the data to be displayed:
{
(string) key - (number) value description
(number) key2 - (string) value2 description
}
Optional:
arg3 - maximum attempts
Returns:
theAnswer, timeStarted, colorEnded[r,g,b]
theAnswer - string - the answer to the question
- number - the value discovered
timeStarted - the time we started working
colorEnded - table - the color when we ended on
]]--
Option B:
--[[
-- doFunction (string arg1, table arg2 [, number arg3])
-- does this amazing function
--
-- Args:
-- arg1 - the name of the frame
-- arg2 - the data to be displayed:
-- {
-- (string) key - (number) value description
-- (number) key2 - (string) value2 description
-- }
--
-- Optional:
-- arg3 - maximum attempts
--
-- Returns:
-- theAnswer, timeStarted, colorEnded[r,g,b]
--
-- theAnswer - string - the answer to the question
-- - number - the value discovered
-- timeStarted - the time we started working
-- colorEnded - table - the color when we ended on
--]]
Please note that because Lua is not strongly typed, its a good idea to mention the type of value you are returning.
Normal Functions
Not all functions need a long description. Especially if its an internal function only your are going to use. Normal functions should specify the filename they are contained in, along with a descriptive name of what they do.
Normal Function Names:
FileName_DoThisThing();
Normal Function Headers likewise just need to contain a short description of what they do and their parameters.
Option A:
--[[ Does Its Thing. Returns: true - it worked false - it failed ]]-- function FileName_DoThis(message, password) end
Option B:
--[[ -- Sends its message to the administrator -- -- Returns: -- true - it worked -- false - it failed --]] function FileName_DoThis(message, password) end
If it has no returns and does a very explicit thing, you can condense it to one line using double square braces:
--[[ Sends the message to the administrator ]]-- function FileName_SendMessageToAdmin(message)
This is acceptable because it is clear from the function name exactly what it is doing.
Trivial Functions (Event Handlers)
Some functions, like event handlers, are not worth commenting. These should be sorted together to the bottom of your lua file and organized by XML element. Simply place a block message denoting their purpose.
Option A:
--[[ Event Handlers ]]--
Option B:
-- -- Event Handlers -- function FileName_CheckButton_OnEvent(event) -- Do Something end function FileName_CheckButton_OnClick() -- Do Something end function FileName_Frame_OnShow() -- Do Something end function FileName_Frame_OnHide() -- Do Something end
Code Examples
If you want to include example usage code for your addon, leave it at the very bottom of the lua file, commented out.
Summary
These style standards are pretty simple and give you a couple options. Please remember to comment your files with headers and have commenting for functions. When you're done with your code others will need to be able to read it.
