Examples of User Friction in Darklang

[clintgibler]

Darklang does many things really well and makes it a pleasure to prototype small tasks. This issue aims to document aspects that have personally caused me friction / annoyance, with the hopes of making Darklang even more of a joy to work with.

1. Not being able to add documentation or namespace user-defined functions

See https://github.com/darklang/dark/issues/2805 for more details.

As you're writing more and more functions, it becomes a bit cluttered to not be able to namespace functions. For example, if you're wrapping a third-party API like Twitter, you intuitively want to group those related functions together under a Twitter:: namespace.

I've been hacking around this currently via the naming convention: twitter_api_<foo>, but it's not ideal.

2. You can only view one function at a time on the canvas

When you're working with HTTP endpoints, REPLs, datastores, and cron's, they're all present on the same canvas and you can rearrange them, look at them next to eachother, etc.

For some reason, functions are different in that you can only look at one of them at a time.

This is a pain, because oftentimes when I'm writing a new function I'm basing it on an existing function or thinking about how it'll be used with an existing function, and I want to see them side by side.

So currently I either need to have two Darklang windows open, or just continually swap between them, which causes unnecessary work.

3. Copy and pasting code usually breaks things

Oftentimes you want to move code between HTTP handlers, REPLs, and/or functions. However, due to the enforced structural editing, copy and pasting usually leads to a broken state and I have to manually type/edit parts of it out again to make the editor happy.

extract-function in theory should fill this role, but in practice it does not. What if you're wanting to copy functionality between an HTTP handler and a REPL, between REPLs, or between functions?

This isn't a core blocker (you can just retype the functionality you want in a new context), but is a bit frustrating.

4. You can't specify a start time for cron elements

For cron components, you can specify certain intervals, but you can't say when you want it to start, it appears to start when you first create the component.

For example, let's say I want to calculate some stats at 10pm every night. Currently I'd have to wait until 10pm to create this cron.

Perhaps even more than not being able to set the time at which a cron runs, it would be nice to have visibility into when it's running (e.g. "Daily at 5pm", "Weekly on Sundays at 7pm", ...) Currently you can infer this by looking at previous times it ran + the run frequency, but that seems unnecessarily opaque.

A more usable UI would be to add to the title of the cron component more info like:

CRON Daily 10pm             update_my_stats    

CRON Weekly Sundays 5pm     check_rss_feeds    

# And maybe include next time it'll trigger
CRON Weekly Sundays 5pm     check_rss_feeds    Next: 2020/09/27 @ 5pm

5. Compound statements are unintuitive

Say I want to do multiple calculations or some sort of compound statement like:

if List::length records_found > 1
  ...

This won't work, because it's resolving it to records_found > 1 (true | false) -> List::length <true or false>.

This can rectified by using the pipe operator in the right place in the right way, but overall I'd say some compound expressions one would trivially write in most languages don't do the right thing on your first try and you need to rewrite them.

Not a blocker, but it adds friction, as it takes a bit of work to get what you want sometimes. Maybe this is a "won't fix" and users will do the right thing once they learn, but especially at the beginning is frustrating.