CONTRIBUTING.md

Contributing

You will find here a summary of the different things you should do / look up to contribute to the project.

Starting

• First, fork the repository
• Then, clone your fork:
  • HTTPS: git clone https://github.com/<username>/Ark.git
  • or SSH: git clone [email protected]:<username>/Ark.git
• Install the pre-commit hooks: pre-commit install (you may need to install pre-commit first)
• Create a branch for your feature: git switch -c feat/my-awesome-idea
• When you're done, push it to your fork and submit a pull request

Don't know what to work on? No worries, we have a list of things to do.

The architecture of the project

For an in-depth explanation: Understanding the project architecture.

For a quick glance at the organization of the project, check this out:

Contributing to a module (or creating one)

The repository for this is ArkScript-lang/modules, and the language used is C++.

See the guide to create a module.

Submitting a pull request

Code formatting as well as static analysis is handled through pre-commit and its hooks. If you don't have it installed, refer back to Contributing#Starting.

Running the test suites

Build the tests using -DARK_TESTS=On. It is strongly recommended to add -DARK_COVERAGE=On to generate coverage reports.

Run the unittests target to:

• run various C++ unit tests,
• run error messages testing,
• run AST & parsing tests,
• run formatting tests,
• run language tests (tests/unittests/resources/LangSuite/)

Generate coverage reports with cmake --build build --target coverage, it will generate HTML files under build/coverage/ (main file is index.html).

C++ coding guidelines

• Avoid auto whenever possible. Using it is tolerated for complex types such as iterators
• Indent with 4 spaces
• Every brace ({, }) must be on its own line
• Conditions with a single statement (eg if (condition) do_this();) do not need to be enclosed in braces
• Put a space between for, while, if and (...), around each = sign (wherever it is, even in for-loops), between #include and the file to include
• Prefer enum class over enum
• Left-const over right-const
• The * and & are part of the type:

// AVOID THIS
int *i = new int(5);
int &j = k;

// PREFERRED
int* i = new int(5);
int& j = k;

• Naming:
  • Methods and functions: camelCase
  • Variables: snake_case
  • Constant expressions: PascalCase
  • Enumeration members: PascalCase
• For-each loops should use const references or rvalue references instead of plain copies:

// AVOID THIS
for (auto value : container)

// PREFERRED
for (const auto& value : container)
for (auto&& value : container)

• For-loops should be optimized whenever possible, as follows:

// AVOID THIS
for (std::size_t i = 0; i < container.size(); ++i)
    ...

// PREFERRED
for (std::size_t i = 0, end = container.size(); i < end; i++)
    ...

• Header-guards should be written using #ifndef, #define and #endif, the define being in MACRO_CASE
• Functions and methods which can not throw exceptions must be marked noexcept
• In header files, have a blank line between each method / function / structure / constant ; also put blank lines around include blocks
• In classes, avoid using this. Prefix every member variable with m_
• In classes, do not define the methods in the header file, only in the source file (unless they are inline or templated)
• Add Doxygen file comments at the top of each newly created header file:

/**
 * @file Lexer.hpp
 * @author Alexandre Plateau ([email protected])
 * @brief Tokenize ArkScript code
 * @version 0.1
 * @date 2020-10-27
 *
 * @copyright Copyright (c) 2020
 *
 */

#include <bla>

code...

Snippet to recapitulate guidelines for headers:

/**
 * @file Lexer.hpp
 * @author Alexandre Plateau ([email protected])
 * @brief Tokenize ArkScript code
 * @version 0.1
 * @date 2020-10-27
 *
 * @copyright Copyright (c) 2020
 *
 */

#ifndef HEADER_GUARD
#define HEADER_GUARD

#include <Ark/Compiler/Something.hpp>
#include <vector>

namespace Ark
{
    /**
     * @brief doxygen documentation about the class
     *
     */
    class Lexer
    {
    public:
        /**
         * @brief doxygen documentation here
         *
         */
        Lexer();

        /**
         * @brief doxygen documentation here
         *
         * @param a_parameter defines the power of the flux capacitor
         */
        void aMethod(const std::string& a_parameter);

    private:
        int m_member;  ///< This is a doxygen comment
    };
}

#endif  // Adding an empty line at the end of each file is strongly advised

ArkScript coding guidelines

Check out the Coding guidelines. We are quite flexible about it, those are just general guidelines to produce a readable ArkScript code.