develooper Front page | perl.perl5.porters | Postings from March 2023

Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc.

Thread Previous | Thread Next
From:
demerphq
Date:
March 18, 2023 15:16
Subject:
Re: Proposal: Standardize to one space after full stops indocumentation, pod, comments, etc.
Message ID:
CANgJU+V12ac1VwqJaAF+2QvQgMq_5MTpGmdvjUt-OzuCKXMoMQ@mail.gmail.com
TLDR: I do not want anyone to stop hacking on my perl becuase of my
proposal, and therefore I withdraw my proposal. My intention is not that
anyone should follow /my/ style, but rather to free myself and the rest of
the developers on the project from thinking about style at all, by using
tooling to enforce /a/ consistent style. The style I proposed is merely the
one that I think is the most available (in terms of tooling) and thus the
least worst option to follow.  I just want to be able to fix the wrapping
on text after it has been search and replaced or otherwise modified with a
keypress or a tool. I do not want spend any more time than absolutely
necessary thinking about style. Computers were supposed to free us from
tedious work, not be the source of new forms of it, and all i want to do is
use tools to ensure that we meet the requirements of our tests and broader
comprehension requirements.

On Fri, 17 Mar 2023 at 18:57, Karl Williamson <public@khwilliamson.com>
wrote:

> On 3/16/23 12:49, demerphq wrote:
> > TLDR: Single space after a full stop is easier to automate, the current
> > standard taught in school, and minimally impacts reading speed. Let us
> > make the standard be one space after a full stop.
> >
>
> The bottom line for me personally, is if this rule were adopted, I would
> quit the project.
>

FWIW. I have mixed feelings about this comment.  The prevailing feeling I
have is that you are a very valuable contributor to the project, and
someone who I consider a friend, and I would hate that an action of mine
was the reason for you to leave the project, so I withdraw the proposal to
make a rule about this.

To repeat, because of what you say here I *withdraw* my rule proposal.

However there is a secondary level which I feel I should mention. This kind
of comment makes me really uncomfortable, as you are essentially saying
"unless the project plays by my rules I will walk". My normal response to
that kind of statement from /anyone/ would be "ok walk then", just on
principle; no person is important enough to the project that they should
get to unilaterally set the rules or hold the project hostage to their
policy demands, and I personally would do my best to avoid making that kind
of statement, and instead would leave it implicit in wording like "Such a
policy would strongly discourage my participation in the project" or
something to that effect. It expresses the same thing but without the
hostage implication that triggers my principled response.

Regardless, I don't want you to walk, especially not over /this/ so I
withdraw the rule proposal. But I really wish that you hadn't said it like
that. It sets an ugly precedent.


>
> One reason is because of muscle memory.  I have been following the two
> spaces rule for quite a bit longer than Damian.  It would be hard for me
> to stop.
>

So what stops you from using tooling like Text::Autoformat, or similar to
format your comments just like I do? Then you wouldnt have to learn to stop
and you would likely save time worrying about how the text is wrapped as
well.

Part of my objection to the two space rule is that I dont want to spend
time thinking about wrapping prose. I want to use software to wrap my
prose. I want to be able to write my text however I like, and then
highlight it and hit a key press, and "poof" have it formatted correctly.
Or I want to write a search and replace, or a perl -i command and fix up a
bunch of things across multiple files, and then be able to easily have the
text autowrapped. Especially as we have tests that will fail if POD text is
too wide.  Reading text that is all "zig-zaggy" in terms of line length is
annoying, having it roughly the same width is a win. Being able to get
prose into that format without a lot of effort is really helpful.

I likely would care much less about this subject if it werent for those
tests. If we ditched the POD lines must be so long tests, then I probably
would not care about wrapping pod as much as I currently do. But we do have
test for line length for POD, and if I rename a constant in our code so it
is wider, and that then results in the POD in some prose you wrote starting
to fail test I want to be able to highlight it and wrap it and move on.


> But more importantly, I would lose respect for a project that sought to
> dictate what's basically an aesthetic issue that has no bearing on the
> correct functioning of our product.  Timtoady abandoned.
>

I dont have an issue with Timtoady. I have an issue with having to tasks
manually that should be delegated to software.  I /loathe/ makework.

Let me illustrate my point here with code style. I do not necessarily want
there to be a single style for code in our files. I like my personal style,
and in the files I created I like that the file follows my style.  However
I know that other folks find my style a little jarring, and I know that
their finger memory is different from mine and they find it hard to follow
my style.  That is why i go out of my way to put documentation in the Perl
code I have contributed to the project for a perltidy recipe that can be
used to format the file correctly. I want others that need to work on the
file be able to forget our style differences, focus on the problem at hand
and use tooling to resolve our differences. So if it were up to me every
perl script we have would have a well defined "perltidy definition block",
and we would have a tool that autoextracts that definition and formats our
files according to its documented rules.

The point here I am making is that I do not want uniformity, I want tooling
that automates these decisions so that I don't have to worry about
the rules. I do not want H. Merijn Brand, nor Abigail (both
contributors who also have what might called an "esoteric style") to adopt
my coding style, I want to use automation so that I don't need to worry
about their styles, and so that other folks don't need to worry about my
own. For instance recently I worked on Porting/sync-with-cpan. This file
contains a mixture of styles, some from Abgail, some from other people. In
a single statement or subroutine there are vestigal elements of multiple
styles,  for instance function calls where there is a space after the
function name and then parenthesized options combined with other function
calls where there is no space.  I find that mixture of different styles
/incredibly/ jarring, and I am never sure what to do.  The normal rule of
thumb from Larry is that people should follow the style of the file.  But
that is hard when it is alien to you and there is no tooling to support it.

All of the above is about code. And luckily perltidy is incredibly powerful
and customizable and its author, Steve Hancock, is a great guy who will add
features to support different peoples style providing he can figure out a
way to do so. Merijn and I both have had patches accepted by him, or
features added by him to reflect our style desires. I *wish* there were a
tool of similar flexibility and capability for our C code. I tried to find
one and basically the options in the C world suck.



> It is not true that tooling is hard.


I just don't agree. I tried and it is hard enough that like Damian I
decided I don't want to play this game. Reminds me of War Games: "The only
way to win is not to play.".

Autoformatting text so it respects the gamut of human formatting
conventions, AND also handles wrapping, and this rule is non-trivial, it is
hard. There are loads of edge cases.


> This pretty much does it:
>         s/\. (*nla: )/.  /g
> It enforces the two space rule.  Use of \B{sb} matching before the dot
> and a lookup hash of exceptions would improve the results.
>

perl -le'$_="Dr. Who etc. and et. al. is a great show."; s/\. (*nla: )/.
 /g; print '
Dr.  Who etc.  and et.  al.  is a great show.

Doesn't look great to me. And it doesn't deal with no leaving trailing
whitespace at the end of a line.


>
> I didn't see anyone say that the two spaces is less readable than
> single.  Rather, the arguments admit the single space has a negative
> effect but try to minimize that importance.


No, that isnt correct. The one with a study said that people who were
trained to put two spaces after a dot had a faster comprehension. For
people who were not trained there was no difference.


> So why standardize on
> something that is less readable (however small you may think it is) when
> we could easily standardize on something that is more readable
>

Because it is not easy.


> The argument that everybody else is doing it are specious.  The links I
> followed say not doing it is because of the advent of proportional
> fonts.  They are assuming a WYSIWYG editor.  But I can't imagine using
> such an editor for writing code or pod.  Those arguments simply are not
> applicable to our situation.
>
> Bringing up "e.g.," and ".t" is also irrelevant as there is no space
> after any period there.
>

Well I mentioned .t because it comes up with automating detecting if
somthing is a full stop or not. Perhaps I should have omitted that point,
but your claim that "e.g." is irrelevant is just wrong as a simple git grep
will show:

git grep -P 'e\.g\. \w' pod | head -n 10
pod/perl5004delta.pod:was called as a plain function (e.g. C<Foo::bar()>),
not a method
pod/perl5004delta.pod:(e.g. C<< Foo->bar() >> or C<< $obj->bar() >>).
pod/perl5004delta.pod:This now works.  (e.g. C<delete @ENV{'PATH',
'MANPATH'}>)
pod/perl5004delta.pod:a fixed value are now inlined (e.g. C<sub PI () {
3.14159 }>).
pod/perl5004delta.pod:requested with the ":flock" tag (e.g. C<use Fcntl
':flock'>).
pod/perl5004delta.pod:were csh (e.g. C<full_csh='/usr/bin/tcsh'>);
otherwise, make them all
pod/perl5005delta.pod:on the operator (e.g. C<CORE::log($x)>) or by
declaring the subroutine
pod/perl5005delta.pod:package, e.g. bless($ref, $p || 'MyPackage');
pod/perl5005delta.pod:e.g. C<&our()>, or C<Foo::our()>.
pod/perl5100delta.pod:(e.g. with C<@ISA = @ISA>).

The cases with POD are great examples of the hidden complexity here that
belies your claim this is easy. "e.g. C<&our()>" is a good example.
Neither dot in "e.g." is a full stop, and neither should have two spaces
after it.


>
> If you recoil at my suggestion of instead enforcing a two-space rule,
> Why?


Because I find myself doing search and replace, or manual edits on existing
prose all the time such that the text grows and changes and requires
rewrapping when I am done. Partly it requires rewrapping because of our POD
tests will *fail* if it isnt rewrapped, and partly it requires rewrapping
for readability.

As I said above, I don't want a specific style, I want to be able to
automate these updates so that when I finish updating comments or POD docs
I can rewrap with software.

Damian has written "Text::Autoformat" so that you can easily do fairly
advanced text wrapping and reformatting activities without having to think
about it.  He extended it to handle C comments at my request recently
(which works pretty well, although I still owe him detailed feedback on it)
and to handle pod directives properly (eg NOT wrapping POD).
Text::Autoformat is really nice, it handles outdenting 'NOTE:' type text,
and various other task (like rewrapping email content) in a nice way that
does a good enough job often enough that I use it for almost all text I do
in my text editor. (Not in gmail obviously.)

If you could point me at a script that wraps or replaces Text::Autoformat
that allows me to do what I can currently do and enforces your desired
formatting rules then I would be fine with using it. Until then I think I
will apply "Timtoady" as you have said here and when I need to reformat
paragraphs you wrote with two spaces after periods I will just let the
tooling replace it with one space and just Not Feel Guilty About It. For
the last while I have been spending time going back through to do the
teduous task of adding the double spaces back.

The source is easier to read,


For you. Not for me. I find reading both styles equally easy.


> and any documentation that gets
> formatted for output will have the formatter's rules imposed upon it.
> Proportional font output will have the spacing evened out between words
> on a line; and the current groff for fixed fonts simply strips off the
> second space.  (The original nroff did honor them.)  This means there is
> essentially no effect on users reading documentation.
>

Like I said, my concern is the time i need to spend to fix comments and
docs. Ideally I would spend as close to 0 time as I can to wrap text. If
reducing that time means giving up double spaces after periods then I am
fine with that. I do not see any impact from it at all personally.


> As another example of tools that work: vim has done a fine job of
> wrapping comment blocks, for decades, without AI.
>

Not in my experience.


>
> And I have come to believe that code should not be reformatted
> automatically at all.  I don't think it can be done well enough.
> (Expanding tabs into the appropriate number of spaces is not really
> reformatting, and is ok.)
>

Aren't you contradicting yourself here? First you say its easy, adn not you
say it can't be done well enough. Which is it?


> Part of that is informed by the recent changes to embed.fnc.  The
> entries are now sorted and grouped better, which is good, but the #if's
> that I and others so carefully wrote out in such a way as to make it
> easier to follow the why and wherefore of them, are trashed.  Often, the
> most important condition has been moved from first to last.


I'd like a solid example of that. I think in most regards getting the
defines right and understanding if you were duplicating a set of defines
was a bigger maintenance burdern than anything that happens now.


> This is a
> big step backwards, making it harder to maintain.
>

I dont agree at all. The older code was much harder to maintain when doing
something like splitting up a large file like regcomp.c or moving code
around between different defines. And the varying ways of writing the list
of defines meant that you could have two identical blocks that were created
by different people and laid our differently from each other.  Making it
more difficult to understand what was happening. And the generated files
that were coming from it would pseudorandomly change due to the way tha the
clauses were sorted together.

I think if you have an issue with embed.fnc you should reach out to me
privately, or via a separate thread. We can adjust the automation as you
wish. But there is no way I will ever agree that we should all just
randomly do what we think looks best and end up a bunch of different styles
in a jumble with no checking or validation or anything like that.



> I write a lot of comments that use vertical alignment to clarify and
> make things easier to read.  It's just not a good idea to try to second
> guess how people have formatted their stuff.  I don't object if others
> want to follow the single space rule for their code; I just am unwilling
> to be forced to follow their aesthetic, nor have my code automatically
> formatted to follow it.
>

The thing is I often find that when you do this it is NOT easier to read,
at least for me, and to make it worse, it is much more costly for me to
update the code after you have done thse things. Every time I am forced to
make a decision about whether I should just ignore your preferences, or if
I should take the time to manually make the code meet what I think are your
preferences and the time I spend wondering if I should do this or that to
avoid having to think about your expectations. (I have posted patches that
replace certain types of code with macros just so that I didnt have to deal
with some of your expectations about how to lay out the code when it became
mult-line.) I would have no objection to this if it was managed by a tool;
I'd just use the tool and be done with it.  But often it requires manual
work that IMO I shouldn't have to do.


> The bottom line from a project point of view is that we already are too
> intrusive in automatic formatting; it can't be done well enough, so we
> shouldn't add more.  And there really is no need to make single space
> (or double space) a standard.  Leave it up to the coder.
>

I dont agee. I think we should be using automatic formatting on everything.
Then everyone is treated equally, we can all learn and get used to whatever
the standard is, and most importantly we won't have to spend time on
dealing with these questions manually.

Some time back a bunch of people got really riled up when I suggested we
change our rules regarding line length. I would much prefer it if we used a
120 or 140 characters per line maximum, instead of the 80
character maximum. But the community as a whole said "no we prefer 80
columns", and I do my best to live with that decision, and in fact that
decision is part of the reason we are having this conversation. 80
characters is sufficiently short that I find that almost any edit to
existing text results in /some/ of the text going over 80 characters. As
such I have invested the time to use tooling to format code and prose to
those line limits. I would like to be able to use even more tooling to meet
these limits.


> If you were one of those who recoiled at the idea of a two space rule.
> Again why?


Because of the dearth of tooling that allows me to automate the task of
laying out text in comments and pod blocks to satisfy it.

We have tests that nag me if my POD lines are too long. POD does not
actually care how long lines are, and I certainly wouldn't willingly
inflict a 80 column rule on myself if I could avoid it. So I want to be
able to edit POD (and comments) and just hit the "reformat text" key in my
editor and have it pass the tests and be reasonably readable. I do NOT want
to waste my time with such matters, I want to automate it away. If I could
reliably automate your style I would and we wouldnt be having this
conversation, but as has been stated elsewhere (including by you), some
types of formatting are "automation unfriendly", and teaching humans is
easier than teaching computers.


I believe I demonstrated it was better than the one space
> one.


I dont think you did. The studies out there show that people who *expect*
the two spaces read less well without it. For those who do not have
that expectation there is no difference. And the difference is extremely
minor even when it is apparent. It is very grey area as to whether it makes
a difference really.



> So why would you recoil?  My guess is it would be that you
> wouldn't want to have my aesthetic imposed on you,


No, that isn't correct. If there was tooling that automated your style
which I could use then I would use it and presumably we wouldn't be having
this conversation. There isn't and I suspect the reason there isn't is
because it is a harder problem than you admit.

> but have no problem imposing yours on me.

Characterizing it as "my style" is not fair. I actually *would* prefer if
all of our comments and docs used the double space after a full stop model,
as I said in my original post I also come from the time period where that
was the standard. The only reason I want to standardize it to a
single space is that there are no good tools to help me achieve that style,
and there is a large group of people younger than me who don't think the
rule exists at all so I want to make them feel comfortable as well.

BTW, as I recall you were one of the people who favoured an 80 column limit
for our code when I was asking for something wider. Why was imposing that
expectation on me ok, but me suggesting this not ok?

The advantage of having a standardized set of tooling which manages
formatting is that it side-steps these kinds of discussions. I don't get
everything I want (140 column text), and you dont everything you want (two
spaces after a full stop), but most importantly we don't argue about who
gets what they want, it comes down to what the tool does or can do.  I dont
want you to have to manually follow /my/ style, and I dont want to have to
manually follow /your/ style. I just want to be able to use a tool so that
I dont have to worry about style at all and leave it up to tooling instead.
If that means I don't get every one of my preferences respected it still is
a big win for me and the project because /nobody has to to think about
it/.  If you gave me a tool that formatted stuff the way you liked, and the
rest of the community agreed we should use it then I would be happy to use
it.


That's not perly.  But it's best to not have such
> a picayune rule at all.
>

Sure, but if we go that way then I reserve the right to reformat any text I
feel necessary to reformat in my style without feeling guilty at all. I
just wanted a rule about this so that it was clear that it is not an error
to replace two spaces after a period with one space if I need to. It seems
that not having a rule has the same outcome, so then I am happy I guess. I
would prefer that we came to a consensus that using specific tooling to
enforce whatever conventions we want to follow is better than expecting
everyone to follow each other's style manually.  Going back to code now, my
experience is that outside of one developer I have worked most people do
have a consistent style even if they think they do. I know from running
perltidy on my own code that I often violate my own preferences in minor
and subtle ways.

Yves


-- 
perl -Mre=debug -e "/just|another|perl|hacker/"

Thread Previous | Thread Next


nntp.perl.org: Perl Programming lists via nntp and http.
Comments to Ask Bjørn Hansen at ask@perl.org | Group listing | About