Using Vim, using tabs, using spaces

[John W. Eaton]

This is pretty far off topic, but I'll send it to the list anyway.

Everyone has their own preference about what looks best, but I see a
lot of people inventing their own indentation styles and very few of
them are any better than the usual styles and most are arguably much
worse.  Maybe Python has it right after all -- make the indentation
necessary for the language and then there will be fewer crazy
variations.

I find it much easier to read a program which has a consistent style
throughout.  Although I prefer the GNU style, if I'm editing code for
another project, I try to use the prevailing style rather than the GNU
style.  Likewise, if you are writing code for Octave, it helps if you
use (more or less) the GNU style.

If we had tools to automatically reformat to our own preference each
time we checked out from CVS or edited a file, then none of this would
matter and we could concentrate on more important things.  And no,
indent won't do, because we need to also be able to convert back to
the One True Style when we check back in, or we need revision control
tools that just store token lists.

On 19-Feb-2005, Steve C. Thompson <address@hidden> wrote:

| Below is the program with spaces.

This is still not quite what the GNU coding standards recommend for
brace levels and spaces around semicolons and parens.

  #include <octave/oct.h>
  #define PI 3.14159265358979

You can get a more precise value of pi from a standard header, so it
would probably be best to use it.

  DEFUN_DLD (sct_complex_matrix, args, , "Returns a complex matrix")

For Octave, I generally prefer the doc string to start on a separate
line.  But I don't think that is required by any of the tools that
manipulate DEFUN macros or docstrings.  I know, this is a small
example, but for Octave the docstring should be formatted with Texinfo
markup.  That way, the output of the help command has a more
consistent appearance and the docstrings can easily be incorporated
into the printed manual.

  {

I generally prefer some whitespace around blocks of code.  Mashing
everything together makes it harder for me to read.

    octave_value retval;

    int subcarrier_number = 128;
    int oversample_factor = 4;

I know this is just an example, but magic constants are generally
bad.  If these numbers could change, they should probably be passed in
as arguments to the function.  You could make them optional.

    int sample_per_block = subcarrier_number * oversample_factor;

    ComplexMatrix subcarrier_matrix(
      subcarrier_number,
      sample_per_block );

I would write the above as

    ComplexMatrix subcarrier_matrix (subcarrier_number, sample_per_block);

Note the spaces around the parens.  They are more like regular
printed text.  Do you see text like this( for example )in other
writing?

    for (int n = 0 ; n < sample_per_block ; n++)
                  ^
                  should not have space here.
    {
    ^
    should be indented two spaces from the preceding for/if/while

      for (int k = 0 ; k < subcarrier_number ; k++)
      {
        subcarrier_matrix(n,k)=Complex(
                              ^
                              should have spaces around =

          cos( 2 * PI * n * k / subcarrier_number),
             ^
             should have a space before the open paren, not after

          sin( 2 * PI * n * k / subcarrier_number) );
                                                  ^
                                                  should not have
                                                  spaces before or
                                                  after close parens.

As I showed earlier, I would probably put the common elements of the
previous expression in a tmp variable so that I could write it all on
one line.  If you do split something across lines, then it should line
up at the open parens, as follows.  Since your variables names are so
long (not all bad) they tend to push the meat of the expression way to
the right.  Also, I tend to not be so religious about the whitespace
around all operators now.

        subcarrier_matrix(n,k) = Complex (cos (2*PI*n*k/subcarrier_number),
                                          sin (2*PI*n*k/subcarrier_number));

In cases like this, I sometimes push the assignment operator to the
next line, like this:

        subcarrier_matrix(n,k)
          = Complex (cos (2*PI*n*k/subcarrier_number),
                     sin (2*PI*n*k/subcarrier_number));

but I still think it looks best with a tmp variable, so you can write

        double tmp = 2*PI*n*k/subcarrier_number;
        subcarrier_matrix(n,k) = Complex (cos (tmp), sin (tmp));

Give tmp a meaningful name if it will help.

      }
    }

    return retval = subcarrier_matrix;
           ^
           prefer to avoid assignments in places like this
           for Octave, you could avoid retval altogether and just
           write

             return octave_value (subcarrier_matrix);

           (the conversion to octave_value_list is automatic).
  }

Another thing that might come up is how to wrap long conditionals like

  if (! retval && not_a_struct && (type == "any" || type == "file") && 
(sr->is_user_function () || sr->is_dld_function ()))

?  The GNU coding standards recommend breaking the expression before
the operator, so it would look like this:

  if (! retval
      && not_a_struct
      && (type == "any" || type == "file")
      && (sr->is_user_function () || sr->is_dld_function ()))


jwe



-------------------------------------------------------------
Octave is freely available under the terms of the GNU GPL.

Octave's home on the web:  http://www.octave.org
How to fund new projects:  http://www.octave.org/funding.html
Subscription information:  http://www.octave.org/archive.html
-------------------------------------------------------------