2.5. Coding Style

Not all code needs to follow the guide perfectly, but it is important to try to maintain a standard of quality.

The SimCenter frontend applications are written in C++. The applications that run in the backend are written in a mixture of languages: Python, C, and C++. The SimCenter strives to use a standard style across the applications. This section outlines that style.

Consistency is the most important aspect of style. The second most important aspect is following a style that the average programmer is used to reading.

2.5.1. Python Style

For code written in Python, SimCenter programmers follow the widely used Guide PEP 8

2.5.2. C/C++ Style

Unlike Python, C/C++ does not have a widely accepted style guideline. Some guidelines of note include the Google Style, the C++ Core Guidelines (edited by Stroustrup and Sutter), and an older C++

2.5.3. Comments

It goes without saying that you must use them. Try to use // as opposed to /* */, making it easier to comment out a block of code when debugging.

2.5.4. Naming Conventions

All names should be meaningful and Follow a camel case approach. For classes, the names start with an uppercase letter; all class methods, functions, and variables shall begin with a lowercase letter. The exception is constant variables, which should be all uppercase, e.g. const double PI=3.14159265358979323;

2.5.5. Files and Interfaces

  1. Use a .cpp extension for code files and a .h extension for interface files.

  2. All files should include at the start the Copyright and License

  3. All files should contain some comments about what the file contains and the name of the developers who worked substantially on the code.

  4. Use indentation to make the code easier to read; the Qt editor has a nice feature that will auto-indent code for you.

  5. In addition, when writing header files:

    1. Never ever ever use using namespace in a header.

    2. All header files should additionally include documentation as the purpose of the class and the methods. The returns and args to the functions should be documented.

    3. Header files MUST contain a distinctly named include guard to avoid problems with including the same header multiple times and to prevent conflicts with headers from other projects.

    4. The comments should be in a Doxygen format.

    5. Assign default values with = or {}, a C++11 feature.

    6. All variables defined in the header must be private.

An example header file.

#ifndef SIMCENTER_WIDGET_H
#define SIMCENTER_WIDGET_H

/* *****************************************************************************
Copyright (c) 2016-2017, The Regents of the University of California (Regents).
All rights reserved.

Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this
   list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice,
   this list of conditions and the following disclaimer in the documentation
   and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

The views and conclusions contained in the software and documentation are those
of the authors and should not be interpreted as representing official policies,
either expressed or implied, of the FreeBSD Project.

REGENTS SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
THE SOFTWARE AND ACCOMPANYING DOCUMENTATION, IF ANY, PROVIDED HEREUNDER IS 
PROVIDED "AS IS". REGENTS HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, 
UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

*************************************************************************** */

/**
 *  @author  fmckenna
 *  @date    2/2017
 *  @version 1.0
 *
 *  @section DESCRIPTION
 *
 *  This is an abstract interface providing interface SimCenter widgets must adhere to. At present limited to
 * providing methods to read and write from/to JSON objects and signals the class can use to invoke slot methods
 * in main window classes. This is to allow uniform handling of error messages in an application comprised of
 * different widgets.
 */

#include <QWidget>
class QJsonObject;

class SimCenterWidget : public QWidget
{
    Q_OBJECT
public:
    explicit SimCenterWidget(QWidget *parent = 0);
    virtual ~SimCenterWidget();
    /** 
     *   @brief outputToJSON method to write all objects data neeed to reconstruct object to JsonObject
     *   @param rvObject the JSON object to be written to
     *   @return bool - true for success, otherwise false
     */  

    virtual bool outputToJSON(QJsonObject &jsonObject);
    /** 
     *   @brief inputFromJSON method to instantiate itself from a JSON object
     *   @param jsonObject the JSON object contaiing data to instantiate the object
     *   @return bool - true for success, otherwise false
     */  
    virtual bool inputFromJSON(QJsonObject &jsonObject);

signals:

    /**
     *   @brief sendFatalMessage signal to be emitted when object needs to shut program down
     *   @param message to be returned
     *   @return void
     */
    void sendFatalMessage(QString message);

    /**
     *   @brief sendErrorMessage signal to be emitted when object needs to communicate error with user
     *   @param message to be returned
     *   @return void
     */
    void sendErrorMessage(QString message);

    /**
     *   @brief sendStatusMessage signal to be emitted when object needs to communicate status with user
     *   @param message to be passed
     *   @return void
     */
    void sendStatusMessage(QString message);



public slots:

private:
};

#endif // SIMCENTER_WIDGET_H

Note

Use 4 spaces per indentation level in both Python and C/C++ when viable.

2.5.6. Variable

  1. Initialize all variables

  2. When initializing float and double variables with values that could be read as integer always include a .0, e.g. double a = 1.0;