Macaw-Movies/Development/Code Rules

From KDE Community Wiki

Naming

  • English is used for all names (class, function, variable…)
  • camelCase is used for all names

Variables

  • Abreviations are not tolerated anywhere in the code. All names must be as explicit as possible
  • members start with m_
  • local variables start with l_
  • function parameter names do not have a specific prefix
  • global variables are prohibited, the few accepted are capitalized
  • class names start with a capital letter

Functions

  • blank line before calling return
  • blank line between two logical blocs

Conditions

The following rules sould be followed (1 space after key word, 1 between condition and curly bracket).

if (variable > 0) {
    ...do something...
} else if (variable == 0) {
    ...do something else...
} else {
    ...do something else...
}

If there is more conditions to fulfill:

if (cond1
   & cond2) {
    ...do something...
}

For the switch/case:

switch (var)
{
case 1:
    fct();
    break;
case 2:
    otherFct();
    break;
}

Debug

Every function should tracable. Do do that, use the Macaw::DEBUG() function.

There are two cases:

  • If the function does a full process (for instance, fill the left pannel),
    • use Macaw::DEBUG_IN("[Classname] Enters functionName()") before doing anything
    • use Macaw::DEBUG_OUT("[Classname] Exites functionName()") after closing the last bracket of the function
    • use Macaw::DEBUG("[Classname] something happens") for showing something;
  • If the function returns a value or don't do much, use only Macaw::DEBUG("[Classname] something happens")

Document

Explain shortly in the header what the function does and what the parameters are, what will be returned

Example:

/**
 * @brief Slot triggered to add the movies of the saved path.
 *
 * 1. Read all the paths
 * 2. For each file:
 *      -# Check that the suffix is correct
 *      -# Check that the file has not been already imported
 *      -# Import the movie in the database
 *      -# Request FetchMetadata to get the metadata on internet
 *      -# Update the movie
 * 3. Request the update of all pannels
 */
void MainWindow::addNewMovies()
{
    Macaw::DEBUG("[MainWindow] Enter addNewMovies");
    .....
    Macaw::DEBUG_OUT("[MainWindow] Exit addNewMovies");
}

or

/**
 * @brief Slot triggered when the user clicks on the About menu.
 * Show the about menu.
 */
void MainWindow::on_actionAbout_triggered()
{
    .....
}