Macaw-Movies/Development/Code Rules: Difference between revisions

From KDE Community Wiki
 
(6 intermediate revisions by the same user not shown)
Line 5: Line 5:
=== Variables ===
=== Variables ===
* Abreviations are not tolerated anywhere in the code. All names must be as explicit as possible
* Abreviations are not tolerated anywhere in the code. All names must be as explicit as possible
* members start with `m_`
* members start with <code>m_</code>
* local variables start with `l_`
* local variables start with <code>l_</code>
* function parameter names do not have a specific prefix
* function parameter names do not have a specific prefix
* global variables are prohibited, the few accepted are capitalized
* global variables are prohibited, the few accepted are capitalized
* class names start with a capital letter
* class names start with a capital letter


=== Functions ===
== Functions ==
* blank line before calling return
* blank line before calling <code>return</code>
* blank line between two logical blocs
* blank line between two logical blocs


 
== Conditions ==
=== Conditions ===
The following rules sould be followed (1 space after key word, 1 between condition and curly bracket).
The following rules sould be followed (1 space after key word, 1 between condition and curly bracket).
{{Input|<syntaxhighlight lang="cpp-qt" line>
{{Input|<syntaxhighlight lang="cpp-qt" line>
Line 44: Line 43:
     otherFct();
     otherFct();
     break;
     break;
}
</syntaxhighlight>}}
== Debug ==
Every function should tracable.
Do do that, use the <code>Macaw::DEBUG()</code> function.
There are two cases:
* If the function does a full process (for instance, fill the left pannel),
** use <code>Macaw::DEBUG_IN("[Classname] Enters functionName()")</code> before doing anything
** use <code>Macaw::DEBUG_OUT("[Classname] Exites functionName()")</code> after closing the last bracket of the function
** use <code>Macaw::DEBUG("[Classname] something happens")</code> for showing something;
* If the function returns a value or don't do much, use only <code>Macaw::DEBUG("[Classname] something happens")</code>
== Document ==
Explain shortly in the header what the function does and what the parameters are, what will be returned
Example:
{{Input|<syntaxhighlight lang="cpp-qt" line>
/**
* @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");
}
</syntaxhighlight>}}
or
{{Input|<syntaxhighlight lang="cpp-qt" line>
/**
* @brief Slot triggered when the user clicks on the About menu.
* Show the about menu.
*/
void MainWindow::on_actionAbout_triggered()
{
    .....
}
}
</syntaxhighlight>}}
</syntaxhighlight>}}

Latest revision as of 14:49, 23 April 2015

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()
{
    .....
}