Amazon prime has delivered a C++ package!
Multi-file projects !
Placing all relevant functions for a program in the same file may be intuitive, however it can quickly become unorganized and hard to find functions you may need to change or update. Additionally, having all the functions in the same files requires that they all be written before your main() function, unless you declare the function before your main() and then define it after. This is known as forward declaration:
#include <iostream>
using namespace std;
// Forward declaration of convert_F_to_C
double convert_F_to_C(double temperature);
int main(void)
{
double temperature = 77;
temperature = convert_F_to_C(temperature);
cout << "Temperature is " << temperature << endl;
return 0;
}
// Function definition
double convert_F_to_C(double temperature)
{
return temperature * 1.8 + 32;
}
Forward declaration tells the complier of the existence of the function, however the linker actually links the definition of the function into main after compiling. This may be necessary to avoid circular dependencies which occurs when two or more modules depend on each other to function properly. However placing a forward declaration into multiple files that require that function is inefficient and messy. Instead, header files ending with .hpp are used to declare a set of functions for source files to use. This way you place all the declarations of the functions your source files require into the header.hpp, and then import it using the include statement at the top of your source file. Thus, we can break up the program above into 3 files, main.cpp, temperature.cpp, and temperature.hpp.
main.cpp:
#include <iostream>
#include "temperature.hpp"
using namespace std;
int main(void)
{
double temperature = 77;
temperature = convert_F_to_C(temperature);
cout << "Temperature is " << temperature << endl;
return 0;
}
temperature.cpp:
// Function definition
double convert_F_to_C(double temperature)
{
return temperature * 1.8 + 32;
}
temperature.hpp:
// Declaration of convert_F_to_C
double convert_F_to_C(double temperature);
Based on convention, files that are a part of the current project are included using quotation marks, but files from libraries are included with angled brackets. To avoid any circular dependency issues it is best practice to include "#pragma once" at the top of the header file, this tells the compiler to include the current file only once during compilation.
Documentation !
To generate C++ documentation a program called Doxygen is used. You can place the documentation into the header file or the source file. There are pros and cons to each but no "right" way, however it is a best practice to choose one way and be consistent. In general, documentation should be up to date and include:
- Short description
- Longer description
- Descriptions of arguments and types
- Description of return and type
- Exceptions and error conditions
- Edge cases
The following is documentation for our function above, placed in the temperature.hpp file above its function declaration.
temperature.hpp:
/*! \brief Converts a temperature from Celsius to Fahrenheit
*
* Given a temperature in Celsius, converts it to Fahrenheit.
*
*
* \param [in] temperature Temperature (in Celsius) to convert
* \return \p temperature converted to Fahrenheit
*/
// Declaration of convert_F_to_C
double convert_F_to_C(double temperature);
At first glance this may seem like a normal C++ comment using /* */, however it starts with a /*! which Doxygen looks for indicating documentation. The \brief command denotes the short description and after the new line, everything is considered the long description. \param denotes the parameter of the function and \return denotes what the function returns. Before stating what the parameter name is, you need to add a tag for how the parameter is used, [in] denotes input, [out] denotes output and [inout] denotes input and output.