Re: Octave line length

[Rik]

On 01/13/2020 11:30 AM, John W. Eaton wrote:
> On 1/13/20 11:02 AM, Rik wrote:
>> How strictly do we want to enforce a line break after the return type in a
>> function declaration?  We mostly do this, but not always.  For example, in
>> Array.cc there is
>>
>> template <typename T>
>> Array<T>
>> Array<T>::permute (const Array<octave_idx_type>& perm_vec_arg, bool inv)
>> const
>>
>> but also
>>
>> template <typename T>
>> T * do_index (const T *src, T *dest, int lev) const
>>
>> And do we want to enforce this convention in .cc files only or also .h
>> files?  For example, Array.h contains
>>
>> octave_idx_type numel (void) const { return len; }
>>
>> which is small and compact, but if enforcing the return type for a function
>> would become
>>
>> octave_idx_type
>> numel (void) const { return len; }
>>
>> There is no problem with declarations in a header file as that is a
>> separate switch to throw in astyle.
>
> The original reason for writing the return type on a separate line was so
> that the function name would begin in column 1.  Then you could easily
> grep for function declarations and definitions using an anchored pattern
> like ^FCN_NAME".  But that doesn't work well for C++ member functions or
> any function inside a namespace declaration if we are indenting all code
> inside a namespace.
>
> Recently, I've been putting the declaration all on one line if possible
> or splitting after the return type if the return type is long.  I don't
> see that there is one rule that will fit all cases.  I just try to do
> what looks best and makes the most sense for each case.

"Beauty is in the eye of the beholder"

This makes sense to me.  I want the tools to help get close to a solution,
but ultimately, I think it comes down to programmer judgment and what
effectively communicates the intent of the code.

With that in mind, I would suggest we stop enforcing an 80-character
limit.  It isn't particularly important given that programmers are working
on 25" HiDPI monitors these days.  Instead, what I value is the clarity of
intent.  If items are grouped together on a single line it is likely
because they are all part of a single idea.  Breaking at an arbitrary point
within an expression thus leads to an incomplete thought which is harder to
understand.  An example from urlwrite.cc is

  std::string filename = args(1).xstring_value ("urlwrite: LOCALFILE must
be a string");

This declares a variable, attempts to initialize it with a string value,
and if that is not possible emits an error.  That is all one single idea
(input processing and validation).  Moving to a vertical coding style just
to stay under an 80-column limit leads to less concise code that isn't any
more effective than the original at communicating what it does

  std::string filename;
  if (! args(1).is_string ())
    error ("urlwrite: LOCALFILE must be a string");
  filename = args(1).string_value ();

The other typical case is we have a rather ordinary expression such as an
if conditional, but it is within a namespace, within a function, within a
for loop, etc.  The overall indent is therefore large, but since it is all
blank space it isn't confusing in any way in the sense that 80 characters
of pure code would be.  In this case, enforcing a line length limit is also
of no real utility.

I'd still say we use some (large-ish) limit in the formatting tools just as
a gentle reminder that extremely long lines are still likely to be confusing.

--Rik