• Download PHPStorm for Linux from JetBrains website.
• Now extract the tarball and run the bin/phpstorm.sh script.
• PHPStorm should start up.

The next step is to configure your license.  In my case, I was using a corporate license server.  The issue with this is that you need to log into JetBrains' website using a special link to activate the license.  Unfortunately:

• By default, WSL doesn't have a browser installed.
• Firefox can't be installed because the default build uses a snap image, and WSL apparently doesn't support snap.
• PHPStorm doesn't appear to be able to properly deal with activating via a Windows browser (I tried pointing it to the Windows Chrome executable and got an error page that points to a port on localhost).

So how do we get around this?  Well, we need to install a browser in WSL and configure PHPStorm to use it.  So here's what we do:

• Skip the registration for now by starting a trial license.
• Download the Vivaldi for Linux DEB package from Vivaldi's website.  You could use a different browser, but I like Vivaldi and it offers a convenient DEB package, so I used that.
• Install the Vivaldi DEB.  WSL will be missing some packages, so you have to run apt install --fix-broken after installing it.
• Go into the PHPStorm settings and configure your web browsers to include Vivaldi and set it as the default browser.
• Go back to the registration dialog and try again.  This time, PHPStorm should start up Vivaldi and direct you to the appropriate link.
• Log into your JetBrains account and follow the instructions.  The web-based portion should succeed and registration should complete when you click "activate" in PHPStorm again.

There we go - PHPStorm is registered and works.  Mildly annoying setup, but not actually that bad.

But the other night I was playing around with my attempt to learn Go by writing a NES emulator.  I'm working from a demo of writing one in Rust, which recommends having highly comprehensive unit tests, so that's what I'm trying to do.  The problem I'm running into is that this results in lots of repetitive test cases.  The individual test cases are short, usually six to ten lines, and take the form of a struct defining the processor state and expectations.  The thing is, there are a lot of them.  By that, I mean that so far I've implemented 20 of around 150 opcodes and my unit test file is already pushing 1000 lines, compared to about 250 lines of production code.

Now, a 4:1 test to prod ratio isn't necessarily a bad thing, but it does seem a little high.  And the tests are all very similar, so they're kind of hard to read and navigate - unless you know the exact term to search for, they all just blend together.  So I really wanted to condense them down, preferably to one line per test case.  So I finally decided to make a few functions to extract the common stuff into a template so that I can condense all those structs down into one-liners.  Great!  But I already have 1000 lines of code to update.  Not so great.

Enter the Vim macro reorder.  For each opcode, a wrote a function to create the test template.  Now I had to take the existing structs and convert those into function calls.  Unfortunately, this was too complex for a simple substitution and it was just too tedious to do that many by hand.  However, the exact same series of steps could be repeated for each test case, so I decided to look up that macro recorder that I've been accidentally turning on for years.

Turns out it's super simple.  You just start recording by using "q" with a register name (e.g. "qa") in command mode, do a bunch of stuff, and then run "q" again to stop.  Then you can execute the macro with "@" and the name, e.g. "@a" and repeat that with "@@".  By itself, this is not terribly remarkable.  But with Vim movements and actions, it's really easy to make a macro that performs a complex manipulation on structurally identical blocks of text.  So I was literally able to start recording, just do the manipulation like I normally would, and then stop recording, leaving me with a macro that works perfectly with basically zero extra work.

Like I said, nothing really new or ground-breaking here.  Just discovering one of those handy features that I've never really used before.  But now I know how to take advantage of that for future use.

At work, we have a PHP project that has automated integration tests written in Python.  The top-level directory of the Git repo is the normal PHP stuff, but the tests/integration/ directory is a Python sub-project that uses Poetry and Pytest.

Now, I use Vim as my editor and CoC with Intelliphense and Pyright for my PHp and Pythong language servers.  Since the main repo is PHP, Intelliphense works just fine.  Hwoever, Pyright needs a little help.  In particular, it didn't find the third-party dependencies or the integration test framework packages because it didn't know where to look.

Fortunately, this is easily fixed by creating a pyrightconfig.json file.  I was able to create one of those in the top-level directory of the project and add an "execution environment" to tell Pyright where to find the root of the Python project.  I set it to the "tests" directory because, while the main dir is tests/integration/,  that directory is also a Python module, so using "tests" lets Pyright find the "integration" module.

My particular file looks like this:

{
    "venvPath": "tests/integration",
    "venv": ".venv",
    "executionEnvironments": [
        {
            "root": "tests
        }
    ]
}

This particular post was expressing my annoyance over how our development environment was broken.  Our dev environment, at the time, was literally just a shared server that we all pushed code to. And yes, that means we had plenty of opportunity to step all over each other and things could easily break for non-obvious reasons.

This was obviously terrible, but it's what we had to work with.  We had a four-man development and system administration team with not a huge budget or set of internal resources.  And, of course, there was always something more important to do than improving our dev environment setup.

These days, I still have dev environment issues, but for completely different reasons.  My company has an entire infrastructure for spinning up development VMs, including dedicated host clusters, custom tooling to setup environments, and teams responsible for managing that stuff.  So now I have my own virtual instance of every server I need (which, for reference, is currently about eight VMs).  However, there are still some holes in that infrastructure.

Part of the issue is that we have a lot of teams that share or depend on the same infrastructure and/or services.  For instance, one of the services that my team maintains is also worked on by at least three other teams.  And we all share the same database schema, which doesn't automatically get updated in dev environments when changes are made in production, so when you pull in the develop branch, you frequently get breaking changes that you may not have ever heard of, usually in the form of config or database changes that aren't set in  your environment.  Sure, everything "just works" if you start fresh, but nobody ever starts fresh because it takes too long to spin up all the required pieces and set up the test data.  (However, we are moving toward a Docker/Kubernetes setup for the pieces that don't need test data, so things are moving in the right direction.)

Not that I can complain too much.  Even for my personal projects, which are much simpler, my dev environment is frequently in disarray.  Things get out of date, permissions or services don't get correctly configured after an update, or my setup is out of sync with the production environment.    In fact, I had that problem just the other day - I pushed some code for this blog that worked fine locally, but broke on the live server because it was running a different version of PHP.  Granted, the code in my dev environment was wrong (and I really should have caught it there), but that's not the point.

The point is that environment maintenance is hard and dev environment maintenance doubly so because it changes frequently and is of much lower priority than production.  That's something I hadn't really had to worry about in my internal IT job, because I was writing desktop apps and everybody was running identical Windows desktops.  It was a a simpler time....

This week's installment of "Pete's list of things that suck" features broken development environments.  I spent the last couple of days at work wrestling with one and it really, really sucks.

The thing is, our development environment is...really screwed.  Things went really bad during the production server upgrade a couple of months ago and we had to hack the hell out of the code just to keep the site running.  As a result, we had all kinds of ugly, server-specific hackery in production which just plain broke when we moved it back into devel.  And since, of course, we have a huge backlog of projects that management wants implemented, we've had no time to go back and reconfigure the development servers.

This week, I've been trying to test some changes to our user upload process.  However, due to some NFS misconfiguration and some code problems, uploads just plain don't work in our main development environment.  We do have a new, additional set of development servers (well, one box with a half-dozen virtual machines, but you get the idea), but I couldn't get those to work either.  Part of it was that the configuration on those servers was incomplete, and part of it was that Firefox sucks.  (Note from the present: I no longer remember why that was.)

Naturally, most of the editing recommendations for Typescript are focused on Visual Studio Code.  But I like Vim, so I did a quick search and found this article, which led me to CoC (which I choose to pronounce "coke", like the soda), which stands for the slightly ungrammatical "Conquer of Completion".  It's a plugin for NeoVim and Vim that essentially does Intellisense (code completion, context popups, etc.) using language servers.

If you're not familiar, the Language Server Protocol (abbreviated LSP, though that always makes me think of the Liskov Substitution Principle) was developed by Microsoft for VS Code.  It's essentially a way to make Intellisense work without the editor having to implement support for each language.  It does this by defining a protocol that "clients" like an editor can use to communicate with a "language server".  The language server is a stand-alone program that can provide code intelligence for a particular language, but is not directly tied to any particular editor.  The server can then be called by any client that implements the protocol, which means that the editor itself doesn't actually have to know anything about the language to implement advanced editing features - which is huge.

Anyway, CoC is an LSP client for Vim.  And I have to say, it's awesome!  I've messed with a few code completion and LSP plugins in the past, but I never really got them to work right.  They were either difficult to configure, or required Vim to be built with particular non-standard options.  But CoC was dead-simple to set up.  The only catch is that you have to install the language servers separately, but it turns out that's super-simple as well.  (The ones I've used so far can all be installed through NPM.)

I'm still getting used to it, but having CoC is a game changer for Vim.  I'd given up on having this level of intelligence in my editor.  I mean, for something that supports as many languages as Vim, building it the old-fashioned way just isn't feasible.  But when you can use the same language servers as more modern editors to do the heavy lifting, suddenly it's no longer crazy.

The next step is to look into the available commands and customizations for CoC and see what I can come up with to optimize my experience.  So far it's a pretty cool tool and it definitely makes the development experience nicer.  I want to see what else I can do with it.

But one of the things that PHPStorm did automatically, which was quite handy, was to add PHPDoc comments to functions automatically.  This is kinda nice because, let's face it, unless you're writing a long description, most of a docblock is just typing.  You duplicate the parameters and return signature and, if the names and types are pretty obvious (which they should be), then there's not really much to say.  But having them is part of the coding standard, so you can't just skip them, even though they don't add much.

Fortunately, Vim has a plugin for that, known as PDV.  It will read the declaration of a function (or class, or a few other things) and auto-generate a docblock for you.  This is nice, but the extension was a little out of date - it hadn't been updated to support return type annotations.  There was a pending pull request to add that, but it hadn't been merged.  I'm not sure why - apparently that repo is dead.

So I decided to just create my own fork and merge the outstanding pull requests.  Now I have a version that supports modern type annotations, which is nice.  While I was at it, I also added an alternative set of templates for NaturalDocs doc comments.  I use NaturalDocs for LnBlog, so I figured it would be nice to be able to auto-generate my docblocks there too.  All I needed to do as add a line to my Sauce config to change the PDV template path.

In this case, I was trying to stash my changes so I could switch to a different branch.  Normally this is as easy as git stash ; git co develop ; git stash pop, but I failed to account for conflicts.  And this time it wasn't the "nice" kind of conflict, where you just fix it and move on with your life.  Noooooo.  This time, I realized that I actually needed to base my changes on the branch I was originally on.  (That branch was due to be merged into develop, but it just hadn't happened yet.)  So fixing the conflicts would have been a waste of time because I'd just have the same conflicts in reverse when I switched back.

But it turns out you can just do a git reset --hard whatever and because of the conflicts, the stashed changes will still be on the top of the stack.  Very handy!  This little nugget saved me a bunch of time.

This article is from way back on March 18, 2007. It actually appears to be finished, so I'm not sure why I never published it. Perhaps I was filled with crippling self doubt that my analysis was actually stupid and people would make fun of me, so I never hit the publish button. That was actually a thing I did for many years. These days, I'm more casual about it. One of the benefits of getting older is that you're more experienced and able to have a more objective view of the quality of your work. Another is that you have a wider perspective on what really matters in life. Another way to put that is "you don't care as much what other people think."

Anyway, this article is about my attempts at implementing the various blogging APIs in LnBlog. This included the Blogger, MetaWeblog, and MoveableType APIs. I guess that seemed like a good idea at the time. In retrospect, it was a nice educational exercise, but not especially useful. I mean, the idea of a generic API that third-party clients can use to post to your blog is great. But in practice, it doesn't seem like that's a thing that many people actually need. I certainly never found a good use-case for it. Maybe that's why the APIs never really got fleshed out.

But that's enough out of present-day me. Let's hear from 2007 me. Enjoy!

Last month, I finally got around to doing some actual testing on the MetaWeblog and Blogger API implementations for LnBlog. By that, I mean that rather than testing it with my own code, I actually installed a few free blogging clients. I learned a few interesting lessons from this.

The Clients

I tested four blogging clients. The first is Deepest Sender 0.7.9, a Firefox extension that supports LiveJournal, Blogger, Wordpress, MSN Spaces, and generic MetaWeblog blogs. The second is KBlogger 0.6.2, a simple KDE panel applet that supports the MetaWeblog and Blogger APIs. Third is QTM 0.4.0, a C++/Qt4 application that support the Blogger, MetaWeblog, and MovableType APIs. Last is BloGTK 1.1, a Python/GTK+ application that also supports Blogger, MW, and MT.

My results were mixed. KBlogger worked basically as advertised. In fact, it's the only one of the clients that seemed to understand the APIs in the same way that I do. The only problem is that it's a bit short on features.

BloGTK seemed to work pretty well. However, it worked best when set to use the MoveableType API. When using the MetaWeblog API, I had problems editing posts. It also has a few weird little bugs, such as things getting messed up when switching accounts.

While it has a nice interface, QTM simply would not work with LnBlog. For the record, this is not my fault but rather due to the fact that this version of QTM did not correctly implement the APIs. When sending calls to the server, it sent blog IDs, post IDs, category IDs, etc. as integers, whereas the specification calls for them to be strings. While the difference may be academic for some servers, LnBlog really does use strings as IDs, so the requests raise errors in the XML-RPC library. (Note: this seems to have been corrected in CVS.)

And as for Deepest Sender, I just can't get it to work as advertised. I don't know why. It can post entries, but editing them results in a hung edit window, the "active blog" box is shrunk down to an unrecongizable control, and I have yet to even see a category selection box.

Server Problems

The first problem I encountered with LnBlog's implementation of the Blogger 1.0 and MetaWeblog APIs was my silly assumption that, just because they are two separate API specifications, I could implement them separately. And so, that's exactly what I did: I wrote one PHP script to implement the Blogger 1.0 API and a different one to implement the MetaWeblog API.

Oh, what a fool I was!

While that attitude made perfect sense when looking just at the specs, it just doesn't work that way in practice. Of the four clients I tested, KBlogger was the only one that worked when the MetaWeblog server didn't implement the Blogger 1.0 API at the same URI. The others all blithely assumed that the same URI would implement the Blogger, MetaWeblog, and MovableType APIs. I guess few people even stopped to consider that a server might have independent implementations of the different APIs. Or perhaps it's just that KBlogger is designed to support clients that only understand Blogger 1.0 while the others assume MetWeblog support. It's hard to tell.

Placing the blame

After going back to look at the specs, I believe much of the blame for this situation rests with the MetaWeblog API specification itself. The problem is that it's just a bad specification. In fact, it's really more a sketch of a specification than an actual spec. It's too vauge, too confusing, and leaves too much open to interpretation.

For instance, take the metaWeblog.getCategories method. According to the specification, this method returns a struct, with each member being a struct with the description, HTML URL, and RSS URL for each category.

For non-programmers, "struct" is short for "structure," and is simply set of key/value pairs. In this case, having member structs with keys for description and URLs makes perfect sense.

However, putting all of these in a struct doesn't make sense. The spec says that the category structs are to be returned in a struct, but says nothing about the key names of this container struct. But the entire point of having a struct is to associate key names with values. A struct with no particular key names is meaningless. It's like writing a book where the index lists words, but not page numbers - if you can't pick the word (key) you want and go straight to the corresponding page (value), then the entire exercise is pointless.

Another shortcoming of the API is that it does not clearly specify a way to identify blog posts. For example, the API includes the metaWeblog.editPost and metaWeblog.getPost methods, both of which take a post ID. It also includes a metaWeblog.getRecentPosts method to get an array of the most recent posts for a blog. You would think that you could call getRecentPosts, let the user pick a post, edit it, and then call editPost to commit the changes to the server. But you can't.

That's because the API does not specify how to get the post ID. The metaWeblog.getPost and metaWeblog.getRecentPosts methods return a struct and an array of structs respectively, and the spec states that the members of these post structs are the members of RSS items. But there is no mention of where the post ID comes in. RSS certainly has no concept of a post ID, so it's not clear which member should be used for that purpose. Presumably, this is why the MovableType extensions to MetaWeblog include a postId field in the post structs.

Of course, RSS does provide a GUID (Globally Uniquie Identifier) field, which seems a natural fit for the post ID. The problem is that the RSS spec does not require that this field be present. It could also be argued that the GUID has a meaning distinct from a blog post ID. But either way, if the MetaWeblog spec meant that the GUID should be the post ID, then it should have said so.

Judging from the MetaWeblog spec, the only place clients can count on getting a postID is from the return value of metaWeblog.newPost. That's fine if the client can assume it is making all posts to a blog, but it is insufficient if there is also, say, a web interface. If your blogging client can only edit posts it created, you've just cut its usefulness in half.

Missing Links

The MetaWeblog API depends heavily on the Blogger 1.0 API. By itself, it is missing too much to be truly useful for the development of rich blogging clients. If nothing else, this is clear from the absence of something resembling blogger.getUsersBlogs.

Actually, that's not entirely fair. There was an RFC to add the Blogger methods to MetaWeblog, so the spec has been amended to correct this shortcoming. Or has it? I actually only learned about this by reading the code for the WordPress MetaWeblog implementation. The "official" MetaWeblog spec doesn't actually mention this or contain a link to the new RFC. That seems rather odd considering that the spec does contain notes regarding other updates. So has the spec been ammended, superceded, or was this just a "Request For Comment" that was never actually adopted?

Bottom Line for Implementers

So what does all this mean for those enterprising individuals who want to try their hand at writing blogging software? It means you've got an up-hill battle.

Don't get me wrong - it's not that implementing the various specifications is difficult. The APIs are actually pretty simple. The problem is that you can't trust them.

For starters, if you want to write a server that is compatible with existing rich blogging clients, you will have to implement the Blogger 1.0, MetaWeblog, and MovableType APIs, and you will have to do it all at the same URI. This isn't really a problem, so much as an inconvenience, as you can't simply work from a single specification at a time, but have to jump back and forth between three of them just to get a workable MetaWeblog implementation.

If you're writing a client, things are just as annoying. As previously mentioned, there's the post ID problem to deal with. Handling that is not difficult, but you have to rely on the good will of the server to send you a sensible post struct, since it is not required to.

If you want to support MovableType, there's also their brain-damaged category handling to deal with. Rather than using MetaWeblog categories, MT has separate mt.getPostCategories and mt.setPostCategories methods, which deal with category IDs rather than textual categories. Again, this is not hard to deal with, but it means you have to implement category handling twice - once for MT, and once for servers that use MW categories. But on the up side, at least MT gives you an explicit postId field.

Conclusion

All in all, the old blogging APIs suck. They're imprecise, lacking in features, and tend not to be so platform-agnostic. I think they can be best described as "just barely adequate."

I have yet to look at the Atom API. I'm hoping it will turn out to be better, but I'm not going to hold out a lot of hope. At the very least, I suppose it can't be any worse than the old APIs.

One of my favorite things about Komodo was that it had pretty good Vim emulation.  I started using that because a few years before I'd spent a lot of time going back and forth between a Windows PC and a Macbook Pro.  The Macbook keyboard had that weird Apple layout going and it routinely messed with me, so I eventually gave up and decided to use Vim-mode because that's the same on both platforms.

Of course, things have changed since then.  I've become a full-time Vim user, and have all the fancy faux-IDE stuff set up.  I actually like it so much that I stopped using PHPStorm for work and switched to doing all my development in Vim.  So this post is no longer relevant to me, but it at least has a few handy links, so enjoy!

I've been a Vim user more or less since I started using Linux.  Mind you, I was never really a hard core Vim user.  I still use the arrow keys, for instance, and manage to get by on maybe a couple dozen keybindings and commands.  I have no clue how Vim's scripting or configuration systems work.  All I know about ctags is that they're a thing that exists.  So really, I'm more of a dabbler.

The other part of this is that I like at least a small amount of IDE in my normal working-day editor.  I kind of like having some sort of "project view" of my files, a code hierarchy viewer, some form of Intellisense, etc.  And while you can get most of the stuff I like in Vim, they're not there out of the box.  And even if you can get them, you can't count on having an obvious graphical way to manipulate them.  Typically, you just have to read the documentation to find out what the key bindings are to trigger everything.

So the upshot of this is that I use Komodo IDE with the Vi emulation setting.  This essentially turns on a Vim emulation mode that makes the editor modal and enables a lot of the standard Vim keybindings as well as a small subset of common commands.  So I get Vim goodness with all the convenience of a full IDE.  I had never really looked closely at just how much of Vim Komodo would emulate, though - I just knew it supported everything I commonly used.

Well, I had some extra time after finishing all my bug fixes the other day, and since really learning Vim has been on my list of things to do for, er, over 10 years, I decided to look up some Vim reference sheets and see how many of the commands and keybindings actually worked in Komodo.  Turns out it was a pretty decent amount.  (Note from the future: I didn't write down the details at the time and don't care enough to catalog now that I no longer use Komodo.  Suffice it do say that Komodo's Vi emulation was actually pretty good.  Maybe not as good as IdeaVim, but pretty good.)

The short-short version of the article is that DropBox originally had the idea to share code between their iOS and Android mobile applications.  After all, why write the same app twice when you can do it once?  Well, it turned out to be a really bad idea.  Because they were doing things for both platforms in a custom, non-standard way, they ended up taking on a lot of extra work just for the sake of re-using the code.  And not just in the amount of extra code they had to write in terms of custom libraries and tools - there's the extra effort of bringing new developers up to speed.  In fact, they eventually realized that it would actually be less work to just write everything twice and ended up abandoning their code-sharing approach.

Of course, this is an extreme case.  Trying to share code between two radically different platforms with different native implementation languages is bound to generate some issues.  A more prosaic example is the left-pad debacle.  You know, the one where a developer removed an 11-line JavaScript "library" from NPM and broke half the internet's deployment scripts.  But in that case, the scale was reversed - instead of trying to share a significant amount of code between a couple of projects, the left-pad package shared a completely trivial amount of code between an absurdly huge number of packages.  But the underlying problem is similar.  By trying to share that 11 lines of JavaScript "the right way", you end up taking on an external dependency that now has to be managed and probably generates more long-term maintenance effort than you saved from not writing the code yourself.  (I mean, seriously, why use a library for something that any half-competent programmer could write in less than 15 minutes?)

On the same theme, I've seen similar problems in client-side JavaScript.  I've worked on a codebase or two where large portions of the front-end were essentially cobbled together out of jQuery plugins that sorta-kinda work together, but not really.  Clearly the intention was to save effort by re-using existing components, but it didn't quite work out.  Sometimes it was because they didn't play well together, other times it was just that one of the components was not very well written.  In a couple of cases, after examining the plugins and the desired behavior, it became apparent that I could just write a version that did work cleanly in an hour or so - less time than it would take to debug the third-party plugin.

Of course, that's not to say that re-using code, whether your own or someone else's, is a bad idea.  It's clearly not.  Sometimes you find yourself writing nearly identical components for multiple projects, in which case it probably makes sense to abstract that into a shared library.  Or maybe there's a third-party library that already does more or less exactly what you need, in which case it probably makes sense to just use it.  That's all fine.

My point is just that "re-use some existing code," like any other idea in engineering, comes with trade-offs.  Sometimes those trade-offs are minor, such as the cost of managing a dependency that buys you a really big chunk of functionality.  Other times, they're pretty major, like the opportunity cost to DropBox of breaking all of the standard platform tooling.  Either way, the important thing is to think about those trade-offs and evaluate them honestly, not just jump to an "easy" answer.