Cacher’s code snippet manager empowers you and your team to get more done, faster. Try all features free.
The following is a completely unscientific, subjective account of writing plugins for Visual Studio Code, Atom Editor, Sublime Text and the IntelliJ Platform. We did not intend for this post to speak for the experience of all plugin developers and our limited experience coding for each platform only grazed the surface of capabilities. With that said, we hope the following adds a data point for those interested in building a plugin for any of these editors.
Cacher Plugin Requirements
One of the fundamental philosophies behind Cacher is the importance of working where the developer works. It was not enough to provide a beautiful and streamlined UX in our web/desktop apps; we had to help coders be productive in their native environments too.
What the plugin needed to do
While using a code editor within a project, developers needed to be able to quickly insert code, either via search or a keyboard shortcut. Ideally, this was done without having to open another application or browser.
Additionally, we wanted to make it easy to create snippets during active development, with minimal interruption to the user’s workflow. The plugin needed to be able to create snippets without taking the user out of the editor. Ideally, there’d be options to assign labels and pick code reviewers during snippet creation.
How we chose which platforms to build for
We based our choices based on two criteria:
- How many developers currently used the editor?
- How easy was it to build a plugin for the platform?
To answer #1, we initially used a sampling of the support tickets and suggestions users sent us. It turned out our estimation roughly correlated with the objective data out there.
StackOverflow’s 2019 Developer Survey is one of the most comprehensive questionaires of software developer habit. It listed Visual Studio Code as the year’s most popular development environment. And thats what we started with.
But while IntelliJ only landed at #4 on the list, the combination of all IntelliJ Platform-based IDEs (IntellJ, Android Studio, PyCharm, PHPStorm, Rubymine) added up to 64.7%. This meant we only had to write a single codebase to target the most popular group of IDEs on the market.
Answering #2 was much more difficult as we couldn’t judge the ease of development without actually developing for the platform. The decision to build for VSCode, then Atom, then Sublime came down to the fact that we could use essentially the same plugin design across all 3 editors.
VSCode, Atom and Sublime are what I’d call TextMate-inspired editors. All three share the basic layout of having a large editor area with a toolbar, a sidebar and an easily-accessible command palette to quickly perform tasks.
It was this command-palette scheme which let us use the same Create Snippet workflow across the editors. To create a snippet, a user would (1) open the command palette, (2) search for the Create Snippet command and (3) use a wizard to pick a library, a title and an optional label.
It is supremely difficult to arrive at a measure of the quality of any development platform. Different developers assign different scores based on how much they like the underlying programming language, the framework and overall coding workflow.
With that said, we’re going to assign scores in several areas on a 1–5 scale (5 being the best), based on our experience writing these plugins. These were the four areas we cared about:
- Framework: Rates the ease of learning plugin development, the framework’s features and overall API design.
- Documentation: A platform is only as good as the number and quality of developers building for it. Good documentation ensures that new devs can get up to speed quickly on its features and experienced devs can find specific information without digging through source code.
- Community Support: When you’re learning a new language or framework, Google and StackOverflow are your best friends. Having an active community on hand means the difference between finding what you need in minutes versus struggling through obscure functions for days.
- Marketplace: A good editor has a healthy plugin marketplace. we rated how easy it was for us to market Cacher and for users to find/install our plugin.
Visual Studio Code
VSCode is the de facto code editor for developers who want something lightweight, powerful but still free-to-use. While it started out looking much like a clone of GitHub’s Atom Editor, VSCode’s awesome IntelliSense gave it inspection features no other open-source editors had at the time of its release.
VSCode is written in Typescript on top of Electron… which happens to be what Cacher is written in. Going from zero to productive on the framework was thus a piece of cake.
Adding commands also happened to be very easy. Each Cacher workflow (Setup, Open snippet, Create snippet) was written using a command hook, with
showInformationMessage calls serving to prompt the user to select an option or input more information.
We took a point off due to the limitations of VSCode’s common capabilities and QuickPick workflow. We were limited to prompting the user for the snippet title and description in separate prompts. We would’ve liked to do what we did for Atom… which was to surface a single form dialog with multiple inputs.
In the next version of the plugin, we’ll be looking to extend the workbench instead of limiting ourselves to the QuickPick interface. Having separate webviews for displaying and creating Cacher snippets would give us a lot more real estate to work with.
We would’ve expected nothing less from the company that gave us the MSDN Library. VSCode’s extension documentation was comprehensive without being overwhelming. Beyond the Getting Started guide, we especially enjoyed the various Extension Guides, with full GitHub repos for each sample project.
Our only criticism: The API reference is sparse on code examples.
Community Support: 5/5
The StackOverflow community around VSCode is very active, as is the issues page on its GitHub repo. We can’t say we made much use of forums given the excellent documentation and VSCode’s ability to
Cmd/Ctrl+Hover over any API function to see its docs… but helpful people are there for you if you need them.
vsce tool made it easy to publish to the marketplace. Our extension’s marketplace listing was based on its
README.md , which allowed for nicely formatted text, bulletpoints and animated GIFs.
Because so much of VSCode’s appeal lies in the ability to customize the editor however you want, Microsoft made it simple for users to discover extensions: by giving extensions its own tab in VSCode’s sidebar. We had no reports of users having trouble finding and installing our extension.
We took a point off due to the strange publisher setup process where we had to create an Azure DevOps Organization in order to publish the extension. More data and analytics around who’s installing the extension would’ve also been good to have.
At this point, Atom is like VSCode-lite. Unless you are devoted to GitHub or just appreciative of all that the project’s done for the Electron framework, there’s little reason to choose Atom over VSCode. With that said, the Atom framework offers a few distinct advantages over its cousin.
What we especially liked about the Atom package framework was its flexibility in building webviews. Atom does not care about what you stick in its modal panel as long it looks like HTML/CSS/JS. We were able to build the Snippet Finder to match that of the Cacher Tray app, with separate files for controller, view, and template.
While you can style webviews however you want (using
.less files), Atom provides a set of built-in classes and
.less variables to help you can use native editor components.
Chapter 3 of Atom’s Flight Manual has a collection of guides on getting started with package development and some general tips and tricks. The examples were fine as introduction to the framework but weren’t as helpful as the full-fledged sample projects VSCode provided.
We had to navigate to separate pages to view each class referenced in the Atom API, which made cross-referencing functions difficult.
Community Support: 4/5
Due to Atom’s decent documentation and our familiarity with ES6, we didn’t have to resort to forums/chat for help building the Atom package. The community on StackOverflow is less active so it might take longer to get your technical questions answered.
Atom’s Plugins marketplace, like VSCode’s, uses the plugin’s
README.md to fill out its listing. But thats where the similarities end. Atom settled on a few design choices that made the marketplace less robust:
- All Atom Packages need to be open-sourced and hosted on GitHub. Depending on where you stand on the open-source debate, this could be a good or bad thing. We would’ve liked to see an option for hosting through a different Git provider.
- There are few options for users to provide detailed feedback through the marketplace. Aside from a Star count and a link to the GitHub repo’s Bugs page, there’s nothing that lets users rate the plugin or ask questions of the developer.
- Atom buries its marketplace within the Settings panel. Users need to take 2 additional steps to search for packages.
Sublime Text earns plaudits for being an exceptionally fast editor, both during startup and for opening large files. We still use it daily to take notes during meetings. That said, development seemed to have tapered off over the last few years and it hasn’t matched VSCode’s cadence of feature/bug releases.
Sublime Text uses Python 3 for plugin development. Python isn’t a language we’ve coded in extensively while developing Cacher so there were lots of Googling how to iterate through lists and the like.
Sublime packages suffer from some of the limitations of VSCode extensions, except even more so. With only a few types of commands, we had to get creative about funneling user inputs through a chain of dialog inputs.
Beyond the limited extensibility options, we also ran into a number of inexplicable bugs during development. Dialog boxes would pop up repeatedly after the user had already entered input, which forced us to put in some de-duping logic just to have things be usable. The web offered no answers.
The Sublime API reference page is comprehensive but short on examples. The official documentation website seems to be skewed towards building themes and language syntaxes. Their official link to How to Create a Sublime Text Plugin references an article from 2011… for Sublime Text 2.
We resorted to the Unofficial Docs to get a basic package up and running. But even code examples there were sparse and lackluster. To learn non-trivial functionality, we really had to dig through the source code for popular packages on packagecontrol.io. For a framework with lots of functions but few best practices, this quickly became an exercise in deciphering which snippet of code applied to our use case.
Community Support: 2/5
As mentioned, we had a particularly hard time getting help during development. There just wasn’t much out there, in terms of StackOverflow answers or tutorials. Unless you’re friends with someone fluent in package development, your best bet would be to find other plugins which match your desired UI elements and learn from their repos.
Sublime Text’s Package Control was built by one software engineer who worked on Sublime and offered it as a free service to the community. While commendable for its attempt to establish a semi-official marketplace for packages, Package Control is deficient in several ways:
- Package Control isn’t native to Sublime Text and requires the user to run a Python script to create a
Packagesfolder and connect to packagecontrol.io. This sets up an obstacle for the casual Sublime user who might not even know the editor offers extensibility options.
- Aside from links to the package’s homepage and issues page, there isn’t a way for users to rate or provide feedback on packages. The Installs chart, while pretty, is not a reliable indicator on the quality of packages.
- Unless your package is Trending or Popular, there’s no way, outside of search, for potential users to discover your package. packagecontrol.io looks as if it hasn’t been updated since 2017 and there’s little chance that a design revamp will come soon.
JetBrains IDEs take a maximalist design philosophy. No matter what type of coding you do, which frameworks you use, what your line-height preference, they have the IDE for you. Given all that they stuff into their JVM-based software, IntelliJ-platform IDEs have a reputation for being slow and resource-heavy, though the situation has gotten better in the past few years.
Full disclaimer: We use Webstorm and Rubymine practically everyday. Thus we’ve gotten used to the types of interface choices that would irritate a dev coming from a lighter-weight editor like VSCode or VIM.
The IntelliJ Platform SDK layers a set of classes, components and services on top of Java Swing. Swing has been around a long, long time… and it shows. The native UI elements look like they’re straight out of 2003 and Oracle has failed to update the visual design to match modern sensibilities. Their official tutorial on how to use Form elements show examples in a Windows XP-style window, complete with thick borders and blue gradients.
IntelliJ tries to improve this situation by introducing higher-level Swing components meant to be used in place of the native ones, with flat-design inspired visual styling. Instead of hacking JTextField to display an autocomplete dropdown, you can just use ComboBox; rather than writing your own modal dialogs using Forms, you can delegate to DialogWrapper. For the most part, we loved using IntelliJ replacements over their native counterparts.
This however, did not take away all the pain of using the IntelliJ SDK. There’s very little hand-holding when it comes to best practices while building plugins. Our initial Forms didn’t scale properly with user resize. We must’ve spent a week wresting with the 8 different layout managers (think CSS flexbox but worse) trying to align content before realizing we could just use the GridLayoutManager that IntelliJ provides.
But once we got the hang of building with Swing, we realized how much the IntelliJ SDK enabled developers to customize the user experience. Whereas in VSCode and Sublime we had to settle for a chain of user prompts to create a snippet, we built the IntelliJ version to match the Cacher dialog almost exactly. The current Cacher plugin barely scratches the surface of what the SDK lets developers do and we’ll be introducing deeper integration in the future.
With great power comes great responsibility… to provide documentation. Unfortunately, this is one area JetBrains doesn’t do well in. Here were some of the issues we ran into using the official SDK DevGuide:
- The documentation was (and still is) missing entire sections.. It has been half a year since we last looked but the sections for Settings, Tasks/Contexts and Element Patterns are still missing docs. Part V — Features, on extending IntelliJ navigation, editing and refactoring, is almost entire bare. Why put disabled links in if there’s no intent to write content?
- While Gradle is the preferred build system for new plugins, most of the tutorial (and examples online) still use the older DevKit system. If you’re not already a Java developer using Gradle, there’s a steep learning curve ahead of you. We ended up just sticking with DevKit.
- There is no API reference. This one really hurt. Not having a centralized documentation of all the classes/methods available meant we had to work through examples and tutorials to glean usable pieces. Ever heard of programcreek.com? Neither did we before starting on IntelliJ. But that was one of the few sites which provided examples of SDK-specific methods being called. Otherwise, the only way we were able to learn was through perusing the IntelliJ IDEA Community Edition source code.
(Edit: JetBrains informed us that you can generate a Javadoc of the API by opening the IntelliJ Community Edition project, then Tools > Generate Javadoc)
Community Support: 2/5
As mentioned, we had a really hard time finding documentation for the API functions we needed. Perhaps due to the languishing status of Java Swing, we also didn’t find much help on StackOverflow or anywhere else online. If you get stuck working on an IntelliJ plugin you’re better off browsing the source code of other plugins to find what you need.
JetBrains put a lot of thoughtful design into their Plugins Repository. There are sections for Featured/Top/New plugins, star ratings/reviews, a place for release notes, links to source code/documentation… even a way to download previous versions.
Most impressive were the verification emails sent out with every new build of the IntelliJ IDE. JetBrains performs automated checks of every plugin in their repository to make sure incompatibilities which lead to missing class/method errors are flagged. The verifier even has its own GitHub repo for you to run checks locally.
Here’s a final tally for our comparison:
Despite the higher scores and superior developer ergonomics of VSCode and Atom, the editor you build for should also take into account market share and overall popularity. For this reason, we’d recommend tackling Visual Studio Code first for its widespread developer adoption, then either JetBrains’ IDEs or Visual Studio (the full-fledged IDE) to address the enterprise market. At this point, Atom and Sublime seem to be dying a slow death, losing market share to VSCode. We wouldn’t recommend building for those editors unless you have a high concentration of users who still use them.
Did you agree with our comparison? Anything you would’ve liked to know more about? Leave your comments below.