Fighting the baddest error of them all: the typo

It's been a while since I posted something in this blog - Been busy enhancing my layer for static-code-analysis over at GitHub - But I'm back to tell you something about the baddest error of them all: the typo.

Over all projects I experienced in my professional life, there were always at least one time when a bug flew in about a typo in an error message or in some documentation file. Mostly release date was near, I had spend days and hours on testing the functionality behind it and all that it was keeping it to become part of the master/product was a single typo?!?!

Why didn't tell some one me that earlier?
Mostly a code review was involved in the process - Had nobody seen this?

The short answer: No! Everybody is going blind after looking at code for a while.

So how to become aware of a typo or a badly written document as early as possible?
If you have been to this blog before, you may the answer: static code analysis!

In the IDE I'm using for most of my project VSCode there is a nice plugin called Spell Checker, which helped me a lot of finding those little things like a "teh" instead of a "the" in a 3000+ line document.

In the YOCTO context we don't have any IDE which offers such a feature. So I kept digging around the web to see how to check for spelling issues in multi language files.

Here are the two that caught my eyes:

• cspell
• textlint

both are using node.js as a backend, which is out-of-the-box usable with current poky layer.

To shown you the results of both tools I injected a sample file into one of the recipes using a slightly bad written snippet I found at https://slulibrary.saintleo.edu/c.php?g=367733&p=2485890

I hate wet and reiny days.

It rained a lot in 1816.... a lot - like everyday; the weather in Europe was abnormally wet because it rained in Switzerland on 130 out of the 183 days from April to September. If I was Mary Shelley I might decide to write a book too. Afterall, it was the onnly thing you could do without TV or anything. She said that she "passed the summer of 1816 in the environs of Geneva...we occasionally amused ourselves with some German stories of ghosts... These tales excited in us a playful desire of imitation"  So, people were stuck inside and bored. Mary Shelley decided to write a book becuase it was so awful outside. I can totally see her point, you know? I guess I would write a novel if there was nothing else to do. 

Both tools ran over it and here are the results

Cspell

[Package:test Tool:cspell] Unknown word:reiny
[Package:test Tool:cspell] Unknown word:Afterall
[Package:test Tool:cspell] Unknown word:onnly
[Package:test Tool:cspell] Unknown word:becuase

Textlint

[Package:test Tool:textlint] reiny -> rainy
[Package:test Tool:textlint] Paragraph: Follow the standard capitalization rules for American English. See https://owl.english.purdue.edu/owl/resource/592/01/
[Package:test Tool:textlint] a -> A
[Package:test Tool:textlint] everyday -> every day
[Package:test Tool:textlint] the -> The
[Package:test Tool:textlint] Paragraph: Follow the standard capitalization rules for American English. See https://owl.english.purdue.edu/owl/resource/592/01/
[Package:test Tool:textlint] error(sentence:uppercase) sentence should start with an uppercase letter Suggestions: => The
[Package:test Tool:textlint] on -> in
[Package:test Tool:textlint] Paragraph: Follow the standard capitalization rules for American English. See https://owl.english.purdue.edu/owl/resource/592/01/
[Package:test Tool:textlint] error(sentence:uppercase) sentence should start with an uppercase letter Suggestions: => Out
[Package:test Tool:textlint] out -> Out
[Package:test Tool:textlint] Shelley I -> Shelley, I
[Package:test Tool:textlint] Afterall ->
[Package:test Tool:textlint] Paragraph: Follow the standard capitalization rules for American English. See https://owl.english.purdue.edu/owl/resource/592/01/
[Package:test Tool:textlint] error(sentence:uppercase) sentence should start with an uppercase letter Suggestions: => It
[Package:test Tool:textlint] it -> It
[Package:test Tool:textlint] "it was" is wordy or unneeded
[Package:test Tool:textlint] onnly -> only
[Package:test Tool:textlint] [he-she] `She` may be insensitive, use `They`, `It` instead
[Package:test Tool:textlint] Avoid using “said”
[Package:test Tool:textlint] [he-she] `she` may be insensitive, use `they`, `it` instead
[Package:test Tool:textlint] we -> We
[Package:test Tool:textlint] error(sentence:uppercase) sentence should start with an uppercase letter Suggestions: => We
[Package:test Tool:textlint] Paragraph: Follow the standard capitalization rules for American English. See https://owl.english.purdue.edu/owl/resource/592/01/
[Package:test Tool:textlint] warning(adverbs) adverbs can weaken meaning
[Package:test Tool:textlint] "occasionally" can weaken meaning
[Package:test Tool:textlint] [german] Be careful with “German”, it’s profane in some cases
[Package:test Tool:textlint] [desire] Be careful with “desire”, it’s profane in some cases
[Package:test Tool:textlint] "So" adds no meaning
[Package:test Tool:textlint] suggestion(so) omit 'So' from the beginning of sentences
[Package:test Tool:textlint] "were stuck" may be passive voice
[Package:test Tool:textlint] This is a commonly misspelled word. Correct it to because
[Package:test Tool:textlint] becuase -> because
[Package:test Tool:textlint] error(sentence:uppercase) sentence should start with an uppercase letter Suggestions: => Was
[Package:test Tool:textlint] Paragraph: Follow the standard capitalization rules for American English. See https://owl.english.purdue.edu/owl/resource/592/01/
[Package:test Tool:textlint] was -> Was
[Package:test Tool:textlint] Avoid using “totally”
[Package:test Tool:textlint] [her-him] `her` may be insensitive, use `their`, `theirs`, `them` instead
[Package:test Tool:textlint] Disallow to use "?".

Interesting is that cspell finds the most of the things which certainly lead to a bug report, but without any assistance how to fix them.
This is textlint plays it's cards. As you see from the results it does not only offer you quick fix up hints it does also analyses a lot more than just typos - it maybe does help you to write better (more precise) documents, a thing everybody who will be working with your code will highly appreciate!

Conclusion

I recently add both tools to my YOCTO-layer, so you can benefit from these tools in your project, without any additional efforts.
Just go to https://github.com/priv-kweihmann/meta-sca for further details.

Why not do it with git-hooks?

Some of you now might say

'Man this seems complicated - I would prefer doing this before a typo is in my repository-code...' 

I admit you're totally right - I would prefer it as well.

On the other hand in YOCTO you are dealing mostly with multiple repositories which are not directly under your control - so for me it seems to be the best option to include the checks into static code analysis framework.
With the results being archived you still have time to reach out to the repository maintainer to get the findings fixed. From my experience most are happy that anybody in participating in their project.

If you have suggestion, comments, feedback please add them in a comment here or write an issue over at GitHub.