# Reporting an Issue
- Report all issues
- Trivial documentation issues welcome ([example](https://github.com/bwapi/bwapi/issues/616))
- Non-trivial feature requests welcome ([example](https://github.com/bwapi/bwapi/issues/393))
# Creating a Pull Request
- Do development on the [`develop`](https://github.com/bwapi/bwapi/tree/develop) branch.
# Versioning
BWAPI versioning is categorized as follows: `major.minor.patch [Beta]`
major | Increased when massive structural changes are made.
minor | Increased when breaking changes are made. Modules will need to be recompiled.
patch | Increased when non-breaking changes are made.
Beta | Appended to a major version increase until stability has been verified.
# Coding Standards
## Spacing
- Use double-spaces instead of tabs. You should be able to convert tabs to spaces automatically in your editor's settings.
- Always indent for each scope level.
- Always put a space between all arithmetic, binary, and conditional operators.
- Don't put a space between function names and the open parenthesis.
- Put a space after a comma.
Examples of spacing
~~~{.cpp}
// bad, can't tell if assignment is a typo, and
// there is a space between the member function and its parameters
if(Broodwar->canMake (UnitTypes::Terran_Marine, builder))
reservedMinerals=-UnitTypes::Terran_Marine.mineralPrice();
// good, the arithmetic is clear
if(Broodwar->canMake(UnitTypes::Terran_Marine, builder))
reservedMinerals = -UnitTypes::Terran_Marine.mineralPrice();
// bad, the scope is not indented, no space following the comma
if ( Broodwar->canMake(UnitTypes::Terran_Marine,builder) )
reservedMinerals = -UnitTypes::Terran_Marine.mineralPrice();
// good, alternative spacing style for if statements
if ( Broodwar->canMake(UnitTypes::Terran_Marine, builder) )
reservedMinerals = -UnitTypes::Terran_Marine.mineralPrice();
~~~
## Formatting
- Use [ANSI style](http://en.wikipedia.org/wiki/Indent_style#Allman_style) braces.
- Break up large single-line if statements to be multi-line if statements.
- Format constructor initializer lists as follows (so that the colon is in the same column as the commas):
~~~{.cpp}
BulletImpl::BulletImpl(BW::CBullet* originalBullet, u16 _index)
: bwOriginalBullet(originalBullet)
, index(_index)
{
}
~~~
## Naming
- Use meaningful names. If a variable's purpose cannot be identified by another project member without analysing the code, then the variable needs to be renamed.
- In local looping scopes, single-letter variable names are generally used as follows:
- `b` for Bullet
- `f` for Force
- `p` for Player
- `r` for Region
- `u` for Unit
- `i` for iterator/index
- Member variables and member function names should be in [lower camel case](http://en.wikipedia.org/wiki/CamelCase). Examples: `getUnitsInRectangle`, `wasSeenByBWAPIPlayer`.
- Constants and macros should be in ALL CAPS and words separated by underscores. Example: `PLAYER_COUNT`
- Use [upper Camel Case](http://en.wikipedia.org/wiki/CamelCase) for classes, structures, enums, and namespaces.
## Hacking
- Offsets must be in hexadecimal. Example: `0x00408CF0`.
- Offsets must be placed in `BW/offsets.h`.
- Avoid using inline assembly unless it is impossible to do so.
- Always perform version checking before making code patches, to maintain partial cross-version compatibility.
## Documentation
- Use the triple slash (`///`) format.
- Try to include as much details on the function as possible. Redundancy can express clarity.
- Include example code if possible.
- Wrap lines before the 100th column.
### Doxygen Generation
- Use `@` for doxygen commands.
- Use `@see` to refer to other functions/classes.
- When introducing a new function, include a `@since` tag with the version number.
- Include `@returns`, and `@retval` where necessary.
- When specifying `@param`, also specify if the argument is optional. Present an indented description on the next line, and also specify its default value if applicable.
### Intellisense Compatibility
- Use the [summary tag](https://msdn.microsoft.com/en-us/library/ms177242.aspx) to wrap the function/class/enum description.
- Use the [param tag](https://msdn.microsoft.com/en-us/library/ms177235.aspx) to identify all of the parameters.
- Identify if an argument is optional with `(optional)` on the same line as the tag.
- Put parameter descriptions indented on the next line, between the tags.
Examples of documentation:
~~~{.cpp}
/// <summary>Sets the size of the text for all calls to drawText following this one.</summary>
///
/// <param name="size"> (optional)
/// The size of the text. This value is one of Text::Size::Enum. If this value is omitted,
/// then a default value of Text::Size::Default is used.
/// </param>
///
/// Example usage
/// @code
/// void ExampleAIModule::onFrame()
/// {
/// // Centers the name of the player in the upper middle of the screen
/// BWAPI::Broodwar->setTextSize(BWAPI::Text::Size::Large);
/// BWAPI::Broodwar->drawTextScreen(BWAPI::Positions::Origin, "%c%c%s",
/// BWAPI::Text::Align_Center,
/// BWAPI::Text::Green,
/// BWAPI::Broodwar->self()->getName().c_str() );
/// BWAPI::Broodwar->setTextSize(); // Set text size back to default
/// }
/// @endcode
/// @see Text::Size::Enum
virtual void setTextSize(Text::Size::Enum size = Text::Size::Default) = 0;
~~~
~~~{.cpp}
/// <summary>Retrieves the region at a given position.</summary>
///
/// <param name="x">
/// The x coordinate, in pixels.
/// </param>
/// <param name="y">
/// The y coordinate, in pixels.
/// </param>
///
/// @returns Pointer to the Region interface at the given position.
/// @retval nullptr if the provided position is not valid (i.e. not within the map bounds).
///
/// @note If the provided position is invalid, the error Errors::Invalid_Parameter is set.
/// @see getAllRegions, getRegion
virtual BWAPI::Region getRegionAt(int x, int y) const = 0;
/// @overload
BWAPI::Region getRegionAt(BWAPI::Position position) const;
~~~
## Language Features
- Use the `nullptr` keyword instead of `NULL`.
- Create move constructors if appropriate.
- Use the `const` keyword where appropriate.
- Use std::array instead of C-style arrays.
- Use explicit enum types (preferably enum class) instead of ints.
- Use in-class member initialization.
- Use the keywords default, delete, override, final, etc.
# Changing the API
## Adding a Virtual Function
1. Add it after all other virtual functions.
2. Label it with Doxygen `@since` tag, indicating the version it was introduced.
Note: Virtual functions are implementation defined, but Visual Studio appears to maintain some consistency regarding the use of virtual functions. Adding a new function to the end will maintain some backwards compatibility.
## Renaming a Function
1. Rename the function.
2. Create a non-virtual function with the old name that calls the new function.
3. Label it with Doxygen `@deprecated` tag and refer to the new function.
4. Optionally add a compiler deprecation warning (until we move to VS 2015).
5. Remove it after the next 2 minor versions or next major version, whichever comes first.
## Deprecating a Function
1. Label it with Doxygen `@deprecated` tag.
2. Provide reason for the deprecation and alternatives if applicable.
3. Optionally add a compiler deprecation warning (until we move to VS 2015).
4. Remove it after the next 2 minor versions or next major version, whichever comes first.