Good Coding Practice

[jhyearsley]

Two questions regarding generally used code formatting practice:

1) When an output will be returned by value what should one name the output in documentation, if anything? E.g. in HW#2 we return by value the number of iterations, but there is no assigned name (i.e the user will choose the name). Is there a preferred format like:

Returns
----------
int : (Return by value.) \\explanation of return

2) I'm wondering what the convention is for using a single line to define a variable versus using one line to define multiple variables, e.g. if I have 9 doubles to initialize is it better practice to go line by line or use a couple lines with multiple variables. I'm sure this could be argued as a matter of personal preference but I'm just wondering if there's any majority thought on this convention.

[cswiercz]

1) The documentation style is based on Numpydoc. The section "5. Returns recommends omitting the colon and anything to the right if the name is not specified.

Returns
-------
int
    Description of anonymous integer value.

2) The preference of style depends on where you're working / who you're working with. In this class I don't judge on style (I would if this class was only 20 students large) but the most important style rule is consistency. If your team or company writes with a certain style then you should adhere to that style.

When I'm working solo on a project I may group variable declarations together if they're closely related or server a similar purpose. If the variable names are long (define "long") then I keep them on separate lines or, usually, if I want to initialize a variable at the same time as declaring it.

int i,j,k;
double start, end;
double pi;
float* A;
float* B = (float*) malloc(...);

Here is a lengthy document on how Google styles their C++ code: https://google.github.io/styleguide/cppguide.html