Where did we lurn to spel?

[Warren Block]

On Thu, 28 Apr 2016, Pedro Giffuni wrote:

> On 04/28/16 16:36, Warren Block wrote:
>> On Thu, 28 Apr 2016, Warren Block wrote:
>> 
>>> On Thu, 28 Apr 2016, Pedro Giffuni wrote:
>>> 
>>>> Hello;
>>>> 
>>>> I just updated locally the textproc/codespell to the latest version
>>>> (bugzilla 209128 for the curious), and it finds a *crazy* amount of
>>>> issues in code comments.
>>>> 
>>>> I can't handle it on my own, indeed I got tired just be checking
>>>> sys/arm ! Anyways, here is what I went "thru":
>>>> 
>>>> https://people.freebsd.org/~pfg/patches/codespell/
>>> 
>>> textproc/igor finds many mistakes, and works on text files, man pages,
>>> DocBook, and HTML.  Use of either of these tools is optional, though.
>>> 
>>> Note: in sys/arm/at91/if_atereg.h, it missed "deines"->"defines".
>> 
>
> Yes, I haven't really reviewed them beyond the initial replacement.
> The changes kept growing and growing and I had to stop.
>
>> Oh, and many of these are contractions, which should be avoided anyway.
>
> Well the main questions are ...
>
> 1) Should someone brave just go ahead and commit massively
> such cleanups?

It is tempting.

> 2) Is there a clever review process to go through these?
> Phabricator with documentation team, or assume common
> sense?

In comments, obvious errors don't need any review.  I saw one change in 
there that changed "safe" to "safely", but the original might have been 
meant as "-safe", like "multiuser-safe".

Those types of changes should be reviewed, and also changes that are not 
to comments, like the output in the last batch.  Maybe the original 
printf output was meant to line up.

> 3) There are many common issues: is "thru" something we should
> accept in comments. How about dont vs don't ?

The old "be generous in what you accept and strict in what you produce" 
saying can apply.  The code is what we produce, and comments should be 
as good as we can make them.  "Thru" is difficult to justify.  "Dont" 
and "cant" could be from trying to avoid an apostrophe.  Just spelling 
out the words instead of using the contraction solves the problem.

We have found in other documentation that bad sections are often copied 
and pasted as templates.  Fixing them avoids later, bigger fixes.