<h1>Adding a Programming Language to Harper</h1>
When I started the <a href="https://github.com/automattic/harper">Harper project</a> I knew I wanted to be able to use it for the comments in my code.
First, because I knew these comments would become part of our official documentation over time, and because I hoped it would encourage me to write more.
Over time, this has become one of the most prized features of the software, attracting tens of thousands of developers.
The common problem, however, is that there have always been programming languages that our LSP doesn't support.
One of the <a href="https://github.com/Automattic/harper/issues/79">oldest issues</a> on GitHub is about this.
This post is a guide for adding a new programming language to the Harper language server.
Why isn't it in the official documentation?
While the information contained within this guide will remain relevant to the project for a long time, I don't imagine each identifier or file path to remain the same.
If you think it would better serve potential contributors to place this guide on the <a href="https://writewithharper.com">main site</a>, let me know.
<h2>Introduction to Tree-sitter</h2>
<a href="https://tree-sitter.github.io/tree-sitter/">Tree-sitter</a> is fantastic framework for building fault-tolerant language parsers.
That means it is still able to parse the majority of a document, even if it contains portions of invalid syntax.
This is important for Harper, since we expect people to use Harper while their programming.
It should be OK if some of their code is incorrect, since we only care about their comments.
There are also a wide variety of Tree-sitter parsers available on <a href="https://crates.io/">crates.io</a>, ripe for our consumption.
If you want to add a language to Harper, this is the easiest way to do so.
<h2>Step 0: Avoid Duplicating Work</h2>
You're interested in adding support for a programming language.
If that's the case, it's possible other people are too.
Make sure no one else has <a href="https://elijahpotter.dev/articles/never_wait">opened a PR</a> or <a href="https://writewithharper.com/docs/integrations/language-server#Supported-Languages">has already merged support</a> for the language you have in mind.
<h2>Step 1: Find a Grammar</h2>
Look for an existing grammar on <a href="https://crates.io">crates.io</a>.
By convention, they tend to be named <code>tree-sitter-&#x3C;language></code>, where <code>&#x3C;language></code> is the language you're looking for. For example, <a href="https://crates.io/crates/tree-sitter-java"><code>tree-sitter-java</code></a> is for Java and <a href="https://crates.io/crates/tree-sitter-rust"><code>tree-sitter-rust</code></a> is for Rust.
If you would rather write your own grammar, make sure it is eventually published on <code>crates.io</code>.
<code>harper-ls</code> binaries are often consumed from <code>crates.io</code>, which requires that all upstream dependencies come from the same source.
<h2>Step 2: Import and Wire In</h2>
Harper's comment support lies in the <code>harper-comments</code> crate in <a href="https://github.com/automattic/harper/">the monorepo</a>.
Import the grammar's crate into the project with Cargo.
<pre><code class="hljs language-bash">cargo add &#x3C;CRATE-NAME>
</code></pre>
Then, add lines to the relevant functions in <code>harper-comments/src/comment_parser.rs</code>.
Make sure you visit the <a href="https://microsoft.github.io/language-server-protocol/">Language Server Protocol Specification</a> to obtain the correct language ID.
<pre><code class="hljs language-rust">pub fn new_from_language_id(
 language_id: &#x26;str,
 markdown_options: MarkdownOptions,
) -> Option&#x3C;Self> {
 let language = match language_id {
 "cmake" => tree_sitter_cmake::LANGUAGE,
 "cpp" => tree_sitter_cpp::LANGUAGE,
 "csharp" => tree_sitter_c_sharp::LANGUAGE,
 "c" => tree_sitter_c::LANGUAGE,
 "dart" => harper_tree_sitter_dart::LANGUAGE,
 "go" => tree_sitter_go::LANGUAGE, // Add a line here
</code></pre>
<pre><code class="hljs language-rust">/// Convert a provided path to a corresponding Language Server Protocol file
/// type.
///
/// Note to contributors: try to keep this in sync with
/// [`Self::new_from_language_id`]
fn filename_to_filetype(path: &#x26;Path) -> Option&#x3C;&#x26;'static str> {
 Some(match path.extension()?.to_str()? {
 "bash" => "shellscript",
 "c" => "c",
 "cmake" => "cmake",
 "cpp" => "cpp",
 "cs" => "csharp", // Add a line here
</code></pre>
<h2>Step 3: Testing</h2>
To make sure everything behaves correctly, we need to add some integration tests.
You'll find all the existing ones under <code>harper-comments/tests/language_support_sources</code>.
Find or write several new files under this directory in the language you've added support for.
Add intentional grammatical errors to these file in syntactically relevant places.
We want to make sure that Harper can detect the errors we want and will ignore the errors we do not want.
For example, we might put an error inside an <code>@param</code> tag in JSDoc.
That way we'll know if Harper is not properly ignoring those elements.
Add new entries to the bottom of <code>harper-comments/tests/language_support.rs</code>.
The second parameter of the <code>create_test!</code> macro is the number of grammatical errors that Harper should detect in that file.
<pre><code class="hljs language-rust">create_test!(ignore_shebang_3.sh, 0);
create_test!(ignore_shebang_4.sh, 1);
create_test!(common.mill, 1);
create_test!(basic_kotlin.kt, 0); // Add a line here
</code></pre>
From there, you can run <code>cargo test</code> to make sure everything passes.
<h2>Step 4: Document</h2>
To advertise support for the language, there are a couple addition places that need modification.
Notably:
<ul>
<li>The supported languages table in <code>packages/web/src/routes/docs/integrations/language-server/+page.md</code></li>
<li>The <a href="https://github.com/Automattic/harper/issues/79">GitHub Issue</a></li>
<li>The <code>activationEvents</code> key in the VS Code plugin's manifest: <code>packages/vscode-plugin/package.json</code></li>
</ul>
<h2>Done!</h2>
That should be everything.
Open a draft pull request while you work and ping me (<a href="https://github.com/elijah-potter/">elijah-potter</a>) if you have any questions.
<h2>Additional Resources</h2>
<ul>
<li><a href="https://github.com/Automattic/harper/pull/1443">PR for adding Solidity support</a></li>
<li><a href="https://github.com/Automattic/harper/pull/970">PR for adding Scala support</a></li>
</ul>

A guide for adding a new programming language to the Harper language server.

A guide for adding a new programming language to the Harper language server.

Adding a Programming Language to Harper

<h1>Quality Is the Most Important Metric</h1>
Harper's Chrome extension continues to come along beautifully. I'm actively working to make it more useful and responsive, slowly crushing bugs that I hear about from our users and contributors. I will not go over them here, since our <a href="https://github.com/Automattic/harper/pulls?q=sort%3Aupdated-desc+is%3Apr+is%3Aclosed">closed pull requests</a> should speak for themselves. I would, however, like to rapid-fire some of the small improvements and ideas about Quality that I've been brewing up this week.
<img src="/images/guggenheim_2.png" alt="Living in a college town is strange. The whole place gets empty in the summer.">
<h2>Quality</h2>
I first heard about big-Q Quality from Zen and the Art of Motorcycle Maintenance by Robert Persig. The book's length—whose main subject is the idea of Quality—speaks to its complexity as a topic. It's a great read, and I'd highly recommend it.
One important point the author makes is that Quality is inherently a human idea. It is hard, if not impossible, to define algorithmically or on paper. When one interacts with an object or a system, they come away with a sense of its Quality, without necessarily knowing exactly what led to that sense.
Some argue that in today's world of LLMs and fast-iterations, the real value of a good software engineer derives from their sense of Quality. We know whether a design decision or change to the code is worth exploring. We know how it will affect users. I don't think this argument is relevant to the LLM discussion at all, but I do agree with it in spirit.
<h2>The Most Important UI Element</h2>
Harper's Chrome extension has one critical UI element that user's should be interacting with more than any other: the suggestion box.
<table>
<thead>
<tr>
<th align="left">Before</th>
<th align="right">After</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left"><img src="/images/before_suggestion_box.png" alt="Before the changes to the suggestion box"></td>
<td align="right"><img src="/images/after_suggestion_box.png" alt="After the changes to the suggestion box"></td>
</tr>
</tbody>
</table>
When Harper locates a problem in a user's text, it underlines it and waits for them to notice. When they do, they have the option to click it and review Harper's suggestion. This is a flow typical of most spell and grammar-checking programs, so you're likely familiar with it. This process makes the contents and behavior of the suggestion box extremely important for user satisfaction.
After receiving some feedback related to the suggestion box's visual unpleasantness and difficulty to understand intuitively, I've started making some modifications. Nothing drastic—I don't want to confuse existing users. I've focused on making it more compact and use more visual storytelling. Now, when a spelling mistake should be corrected, it shows an icon rather than a full "Add to dictionary" label. I'm already getting positive feedback about the changes.
All-in, it seems like much of the design philosophy of the UI is being pushed further in the direction of Harper's core tenet: to get out of the way.
<h1>Why Quality is Important</h1>
<img src="/images/chrome_web_store_front_page.png" alt="The Chrome Web Store Front Page">
Quality is important for the Chrome extension (more so than other integrations) because of the Chrome Web Store's front page.
Extensions that get featured on the front page get a significant amount of free advertising. Millions of users view this page monthly. Getting on the page is guarantee of tens of thousands of new users, if not more.
Here's the rub: you can't get on the front page by paying for it or by chance. An extension is placed on the front page if and only if it meets a high bar of value and quality. In other words: you have to earn it. This is the essential reason why I've been working so hard on Quality these past few weeks: I'm trying to get on the front page.
Most of the steps I've taken in this direction are small enough to not be worth mentioning here. If you're curious, feel free to reach out!

After receiving some feedback related to the suggestion box's visual unpleasantness and difficulty to understand intuitively, I've started making some modifications. Nothing drastic—I don't want to confuse existing users.

After receiving some feedback related to the suggestion box's visual unpleasantness and difficulty to understand intuitively, I've started making some modifications. Nothing drastic—I don't want to confuse existing users.

Quality Is the Most Important Metric

<h1>Why Rust Might Attract More Developers Than Java and JavaScript</h1>
Rust is undeniably a greatly appreciated language, after all, it has placed as "#1 Most Loved Programming Language" on the StackOverflow Developer Survey for 6th year running.
Reading this, you are probably very aware of why so many people like it, but I will be going over those reasons anyway, at least before I reveal its secret weapon.
It’s fast, very fast. While it may not be a great benchmark, The Computer Language Benchmarks Game, measures that it falls just a hair behind the fastest language, C.
That makes sense, given that Rust was meant to replace C/C++. Even better than the benchmark, it has been shown that in many situations, the Rust compiler is able to optimize code significantly better than C or C++, just because it has more information about the developers intent.
It’s consistent. For more than pretty much any other language, Rust developers can expect that, if their code compiles, it works. When it doesn’t compile, the compiler gives better feedback and advice than any other language. It can even check if your arithmetic is wrong.
It’s complicated, but only where it needs to be. The language itself, as well as its standard library are built very consciously, by its users. Most places where you might find you have to write tedious boilerplate, Rust makes it easy. It also gives you the freedom to write code that does exactly what you want, exactly how you want. We will get back to this later.
<h2>The Problem</h2>
When starting a new project what is the first thing you are going to do? It depends on what stack you are using.
If you want to use NodeJS, it might look something like:
<pre><code class="hljs language-bash">mkdir new_project
touch index.js
npm install
</code></pre>
That is just the bare minimum. If you want to add any dependencies, you have to go through an unreasonable number of hoops, and the standard package repository, npm, is known for being quite insecure, not to mention it being controlled by a private corporation.
If you want to use Java, you have to use some kind of template, otherwise it’s impossible to create a project from scratch. Even then, you have to decide between two or three package managers, and deal with it when libraries don’t support your choice.
If you want to use C or C++ forget it. As a beginner, you are going to be stuck figuring out how to use the local linker and compiler to get any library to work.
<h2>The Rusty Solution</h2>
Cargo is one of the simplest, easiest to use build tools out there. It does everything you might need, and it may be why Rust may soon become a major player. 99% of the time, you can just copy and paste a given library’s string directly from <a href="https://crates.io">crates.io</a>, which is a repository owned and operated by the Rust Foundation, and you are off to the races.
Testing is easy too, just run <code>cargo test</code>, and you're done. It covers both unit tests, and integration tests if you need it.
`cargo doc`` provides a consistent, and easy way to document code. It’s also great for users, allowing developers access to a straightforward representation of what a library looks like.
It’s extensible, some of the greatest binary crates out there exist to extend the functionality. So, in the few areas where <code>cargo</code> on its own doesn’t cut it, there are additional crates to fill the gaps.
<h2>Closing</h2>
At least for the moment, of all the great reasons to use Rust, <code>cargo</code> will be the most significant reason it will increase in popularity.
<img src="/images/most_loved_stackoverflow_2021.png" alt="Most loved programming languages, according to the 2021 StackOverflow Developer Survey">
Rust can be tough to learn, especially for people who are used to dynamic languages like JavaScript. But what Rust has beat for most languages is the build system. <code>cargo</code> alone makes Rust more approachable than C/C++, Java and many others.
More and more new developers will be going to Rust instead of those other languages, because it is easier to start with, easier to learn, and has a great community to request help from.

A key part of Rust is far better than what JavaScript has to offer.

A key part of Rust is far better than what JavaScript has to offer.

Why Rust May Be More Attractive than JavaScript

never_wait

<h1>Never Wait</h1>
<blockquote>
Preface: This post is specifically about Pull Requests for <a href="https://github.com/Automattic/harper">Harper</a>.
Read the contributor guidelines for a project before opening a PR.
</blockquote>
I get it.
Opening a pull request is an intimidating proposition.
It is non-trivial to put your blood, sweat, and (let's be honest) tears into code and put that onto the internet for the world to see.
I remember my first pull-request: it wasn't pretty either.
But I want to highlight a couple reasons why I want potential contributors to open their pull requests as early as possible.
<h2>Drafts Reduce Duplicate Work</h2>
When a contributor to a project is assessing the viability or usefulness of some work they're preparing to do,
most look at existing Pull Requests first.
Even if you're still working on the patch, it's a great idea to open a "draft" PR so no one starts work that could go to waste.
Further, if you have a draft open whose CI is failing, a maintainer may see it and fix whatever the problem may be.
I find myself frequently browsing <a href="https://github.com/Automattic/harper/pulls">Harper's Pull Requests</a> looking for failing builds, since I'm often the best equipped to find the issue.
<h2>It Helps With Debugging</h2>
I try to make myself available to contributors in case they have any questions regarding the architecture of Harper.
I'm also game to help debug their code, partly because I am of the opinion that debugging is a skill which is best learned by example.
But it is hard for me to debug code if I don't have it.
If a draft PR has been opened, I can usually see the problem without even cloning the code, since our CI is so comprehensive.
<h2>Conclusion</h2>
So please don't wait; open that PR.
I am thrilled each time I see a name I don't recognize on a GitHub notification.

Elijah Potter

Never Wait

Drafts Reduce Duplicate Work

It Helps With Debugging

Conclusion

Other Stuff

Adding a Programming Language to Harper

Quality Is the Most Important Metric

Why Rust May Be More Attractive than JavaScript