DEV Community: Alvaro Videla

HTML is a programming language

Alvaro Videla — Tue, 02 Feb 2021 21:44:47 +0000

Every now and then we read debates that HTML is a programming language, that it isn't a programming language... I don't understand the point of the debate. It seems to come from a group of people that want to gatekeep who gets to be called a programmer. In any case, having this debate without defining what we understand as programming language makes no sense. So let's look into that.

The canonical source when it comes to programming language classifications is Jean E. Sammet 1969 book Programming Languages: History and Fundamentals. She was an early computer pioneer, where she helped design COBOL among other programming languages. She was the first female president of the ACM so that says a lot about her career impact in computer science.

In that book she provides a couple of defining characteristics for programming languages. Let's see if HTML meets them:

Machine Knowledge Is Unnecessary

In this case "a programming language requires no knowledge of the machine code by the user". The user shouldn't learn about registers, how numbers are represented by the machine, and so on. This doesn't not mean, as Sammet clarifies, that the programmer cannot learn about these characteristic of the machine in order to write better programs, is that it is not required to know them to use the language.

HTML meets this characteristic.

Potential for Conversion to Other Computers

From the previous characteristic we can derive the second one. If the user can ignore the machine in which the program is going to run, a programming language thus must be able to be ported to different machines. Programming languages should be machine independent as Sammet says.

HTML meets this characteristic. It runs in every browser in most modern computers out there.

Instruction Explosion

In this case when the program is translated to machine code, each statement in the program should produce multiple machine code instructions. Also says Sammet, the user doesn't need to write any of this machine code for their program to work.

HTML meets this characteristic.

Problem-Oriented Notation

"A programming language should have a notation which is somewhat closer to the specific problem being solved than is normal machine code". So instead of doing:

CLA C
MPY D
ADD B
STO A

A problem oriented language would have a syntax like this:

A = B + C * D

HTML meets this characteristic. It's pretty clear that HTML fits this requirement.

So based on her selection criteria I would assume that HTML would have made it into her book mentioned above.

Where is Turing Completeness?

As you can see, in Sammet requirements for programming languages, Turing completeness is not part of them. Even more, Alan Turing is not cited in the book, among the hundreds of references cited there, not one of the was Turing. Which makes us wonder what was the influence his ideas had back in the 60s when we had the programming language explosion.

Programming Advice From 1976

Alvaro Videla — Mon, 18 Jan 2021 23:05:35 +0000

This week landed in my inbox the book Software Reliability - Principles and Practices, by Glenford J. Myers from the IBM Systems Research Institute. It's a great book with tons of advice that's very relevant today, even though it was published over forty years ago.

The topic being Software Reliability, one might think that the whole book talks about fault tolerance techniques, algorithms, and so on. While that's part of the book, it's not its main theme. The book focuses on the human aspect of programming, and how making improvements there results in software that's more reliable, because it has less bugs, it's easier to maintain, it easier to use for final users, and so on.

In a section about programming clarity we find the following quote:

The programmer’s goal must be writing source code for the primary audience of people instead of machines.

Code that's easier for other humans to understand and read. So when it comes to project maintenance, people can tell what a program is doing. When everything is on fire due to a bug in production, nobody will care how fast that code was written, but people will care if they understand the code, and they are able to fix the issue.

Even in 1976, the idea of writing code for humans to read, wasn't new. In the 1967 Datamation issue there was an article called What A Programmer Does. One of the best unknown articles about best programming practices out there. The author says:

A programmer does not primarily write code; rather, he primarily writes to another programmer about his problem solution. The understanding of this fact is the final step in his maturation as a technician.

A program is a way to instruct a computer how to perform a task for a certain problem, but at the same time, that text is a document that tells other programmers how that problem was solved. How important it is to write readable code! We must write code with our peers in mind, and let the compiler worry of warning us when the computer won't understand something.

The question is how do we make code that's easier to understand? To start there's a lot of advice out there about how to write clean code, or as Myers calls it in his book "Programming Style". He mentions as inspiration the excellent book The Elements of Programming Style by Kernighan and Plauger. The section provides guidelines like "Use meaningful variable names", or "Do not alter the value of the iteration variable within a loop". While I think these are all good advice, I also think we should dig a bit deeper on what it means to write code that's easier to understand.

To that end, I've been reading about literary theory and seeing how to bring learnings from that field into programming. While I won't repeat myself here, I'll link you to the article Lector in Codigo which I wrote as a first introduction to this topic. Recently I wrote an article applying these ideas while reading Visual Studio Code own source code.

This area has a lot to explore, so expect more articles bridging these two disciplines together.

Appendix

The idea of programming for other humans to read has appeared many times. Here's a few more instances:

Knuth talks about it in his 1983 Literate Programming paper:

Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do.

Of course this idea kept coming back. It's part of the 1985 book Structure and Interpretation of Computer Programs:

Thus, programs must be written for people to read, and only incidentally for machines to execute.

Finally in the book 10 PRINT CHR$(205.5+RND(1)); : GOTO 10 Manfort et al. analyze the line of code from the book title, saying that:

the presence of these optional spaces indicates some concern for the people who will deal with this code, rather than merely the machine that will process it.

This idea keeps coming over and over again. We programmers don't seem to learn.

How to upload images to Blob Storage using Serverless and Static Web Apps

Alvaro Videla — Thu, 17 Sep 2020 15:31:09 +0000

If you have an app that's accessed publicly via the browser, you want to restrict who's able to upload images to your storage backend, but by going the way of Azure Static Web Apps, you are presented with the problem of how to authenticate users towards Azure Blob Storage. Luckily, there's a solution for that. Add an Azure Functions backend that takes care of generating SAS Keys so your users can upload pictures directly to Azure Blob Storage without needing to create an account inside our systems.

You can access the source code for this example here on GitHub: videlalvaro/upload_image.

ServerlessSeptember

This article is part of #ServerlessSeptember. You'll find other helpful articles, detailed tutorials, and videos in this all-things-Serverless content collection. New articles from community members and cloud advocates are published every week from Monday to Thursday through September.

Find out more about how Microsoft Azure enables your Serverless functions at https://docs.microsoft.com/azure/azure-functions/.

What we are building

Here are the steps of what you need to do to accomplish that:

Setup Azure Blob Storage
Create an Azure Functions API for your frontend
Create the HTML/JS/CSS frontend for your app
Learn how to run your app in Visual Studio Code

To complete this tutorial you will need an Azure Account. Follow this link to signup for free.

Setting up Azure Blob Storage

Once you have registered your account on Azure, log in and create an Azure Storage Account called uploadimagesample (feel free to use any other name you prefer). You can do that by clicking the big plus button that says "Create a new resource", and then type "Storage Account" in the "Search the Marketplace" bar.

Create a container

Then navigate to your new storage account, select Containers below, and create a new container called images.

Follow this link to learn more on how to create a container

Setup CORS

Now it's time to set up CORS for your storage account. This will allow your app to send data from your own domain to Azure via HTTP, and circumvent the same-origin policy from browsers.

As you can see from the image, you need to setup a * for Allowed origins, Allowed headers, and Exposed headers. Also select the HTTP verbs that you want to allow, and leave the Max age value as is. If you want later you can customize these values to fit your needs.

Now that you have set up Azure Blob Storage for image upload, it's time to create your Azure Functions API.

Creating the Serverless backend

For a client to be able to use anonymous authentication when sending data to Azure Blob Storage they would need to have a SAS key allowing them to perform their requests. You are going to create a serverless API that creates such a key, and sends it to the browser.

Create a new folder for the project called upload_image, and then open that folder in Visual Studio Code. Then press F1 and select Azure Functions: Create New Project. Choose JavaScript as the programming language, and finally HTTP trigger as the template for your new serverless function. The name for the function will be credentials, and the Authorization level Anonymous.

If you haven't done so, you need to install Azure Functions Core Tools to run the project locally.

Configure your storage connection

The last step to configure Azure Blob Storage is to tell Visual Studio Code how to connect to your storage account. For that go to Azure Portal and open the Access Keys section in your storage account. Grab the Connection String.

Open the file called local.settings.json at the root of your project. There, edit the AzureWebJobsStorage key to include the storage connection string you just obtained from Azure Portal. See picture above. Keep in mind this information is private, so do not commit this file to git!

It should look like this, but with your actual connection string:



{
    "IsEncrypted": false,
    "Values": {
      "AzureWebJobsStorage": "DefaultEndpointsProtocol=https;AccountName=youraccountname;AccountKey=<SecretAccountKey>;EndpointSuffix=core.windows.net",
      "FUNCTIONS_WORKER_RUNTIME": "node"
    }
  }

Now it's time to implement your serverless function.

How to generate a SAS Key with Serverless

To generate a SAS key that can be used to authenticate to Azure anonymously, you need to install the Azure SDK for blob storage:



 npm install @azure/storage-blob

From the storage-blob SDK we are going to use the function generateBlobSASQueryParameters that creates a query string with the right authentication info that will let a client upload images to storage. That function requires a containerName, a set of permissions like read, write, etc., an expiresOn parameter for the SAS key, and a StorageSharedKeyCredential with the authentication info from your connection string. You are going to implement a function called generateSasToken that will take care of that process.

Open the index.js file from your credentials folder and add the following function at the bottom:



function generateSasToken(connectionString, container, permissions) {
    const { accountKey, accountName, url } = extractConnectionStringParts(connectionString);
    const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey.toString('base64'));

    var expiryDate = new Date();
    expiryDate.setHours(expiryDate.getHours() + 2);

    const sasKey = generateBlobSASQueryParameters({
        containerName: container,
        permissions: ContainerSASPermissions.parse(permissions),
        expiresOn: expiryDate,
    }, sharedKeyCredential);

    return {
        sasKey: sasKey.toString(),
        url: url
    };
}

The function generateSasToken takes a connectionString like the one you just copied into local.settings.json and parses it by calling the extractConnectionStringParts function to extract values like AccountKey or AccountName.

Then we create a StorageSharedKeyCredential by providing the accountName and accountKey you just extracted. In the case of the accountKey, you need to convert it to string using the base64 encoding, because it comes out as a Buffer from the parser function.

Next you need to set an expiry date for the generated key. So you can create a Date object and then set its time to two hours in the future. You can change the expiry time to adapt to your use case.

With everything in place you can call generateBlobSASQueryParameters from the @azure/storage-blob SDK and obtain the sasKey. Finally the return value of the function is the query string that includes our sasKey, and the URL that points to our storage instance.

Now it's time to implement the serverless function that will send the results from generateSasToken to the client. As you can see the function is quite basic:



module.exports = async function (context, req) {
    const permissions = 'c';
    const container = 'images';
    context.res = {
        body: generateSasToken(process.env.AzureWebJobsStorage, container, permissions)
    };
    context.done();
};

Here you can specify the storage permissions you are giving to the users, in this case just c that stands for create permissions. Then the container is called images, like the one you created above. From the process.env.AzureWebJobsStorage environment variable you can obtain the value that you set up in your local.settings.json file.

When you deploy this function to Azure, you need to setup the AzureWebJobsStorage variable in your app settings.

Take a look at the final index.js file in the repo to find the required imports for your serverless functions, and also to find the utils.js module that includes the extractConnectionStringParts function.

The next step is to implement the frontend part to contact your serverless API and upload the image to Azure Blob Storage.

Create the Static Web App Frontend

Start by creating an index.html file in the root folder, and add the following code to it:



<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Azure Blob Storage Image Upload</title>
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bulma@0.9.0/css/bulma.min.css">
  </head>
  <body>
  <section class="section">
    <div class="container">
      <h1 class="title">Loading SASKey from the API: </h1>
      <pre id="name">...</pre>
      <br>
      <label for="image">Choose a profile picture:</label>
      <input type="file" id="image" name="image" accept="image/png, image/jpeg">
    </div>
  </section>
  <script src="./dist/main.js" type="text/javascript"></script>
    <script>
        (async function () {
            const {url, sasKey} = (await fetch("/api/credentials")).json();
            document.querySelector('#name').textContent = `SAS Key: ${sasKey}` + "\n" + `URL: ${url}`;
            function 'images', () {
                const file = document.getElementById('image').files[0];
                blobUpload(file, url, 'images', sasKey);
            };
            const fileInput = document.getElementById('image');
            fileInput.addEventListener("change", uploadFile);
        }())
    </script>
  </body>
</html>

Let's focus our attention on that <script /> segment. There you have an async function that will query the serverless API by calling fetch("/api/credentials"). That call will get you the url and sasKey values you generated earlier in the serverless function.

Then whenever the user selects a file, the change event from the file selector will fire, calling the uploadFile function. There we get the file information and pass it to the blobUpload function, so the file is uploaded to Azure Blob Storage. The function accepts the file object, a target URL, a container name, and SAS key.

To implement the blobUpload function, create a src folder and add an index.js file there. Then insert the following code:



const { BlockBlobClient, AnonymousCredential } = require("@azure/storage-blob");

blobUpload = function(file, url, container, sasKey) {
    var blobName = buildBlobName(file);
    var login = `${url}/${container}/${blobName}?${sasKey}`;
    var blockBlobClient = new BlockBlobClient(login, new AnonymousCredential());
    blockBlobClient.uploadBrowserData(file);
}

function buildBlobName(file) {
    var filename = file.name.substring(0, file.name.lastIndexOf('.'));
    var ext = file.name.substring(file.name.lastIndexOf('.'));
    return filename + '_' + Math.random().toString(16).slice(2) + ext;
}

The Azure Blob Storage Javascript SDK provides a BlockBlobClient class that comes with a uploadBrowserData method. You are going to use that to upload images to Azure Blob Storage.

To create a BlockBlobClient you'll need the login information, which consists of the URL including the query string that contains your SAS Key, and an AnonymousCredential instance to tell the BlockBlobClient how to authenticate to Azure.

The login information has the following format: ${url}/${container}/${blobName}?${sasKey}. url and sasKey was the data you got from the serverless function call. blobName is a randomly generated name for the uploaded image obtained by calling buildBlobName.

Now there's a very important detail in the require at the top of the file. You are requiring a node.js module in JavaScript code that will run in the frontend. For that to work you need to use Webpack to do the proper transformation.

Using the Azure Blob Storage SDK with Webpack

Install Webpack by running the following command in your projects root folder:



npm install webpack --save-dev
npm install webpack-cli --save-dev

Then run webpack by typing:



 webpack --mode=development

That command will extract the relevant files from the @azure/storage-blob SDK and make them compatible with the browser execution environment. The generated files will live in the dist folder.

Now you are ready to test the app and start uploading images to Azure Blob Storage.

Testing the app

Let's start by running the Azure Functions backend. Pressing F5 in Visual Studio Code should do the. You should see something like this:

To run the Static Web App locally you need to install the Live Server extension for visual studio code. Once it's installed, then press F1 and enter Open with Live Server. This will open a browser tab with the project running there:

Select an image from your computer and upload it to Azure Blob Storage. If all went well, we should see the image in the Storage Explorer:

Congrats! You just uploaded an image from an Azure Static Web App using Azure Functions to generate the SAS Key!

What to do next

Learn more about Azure Functions
Learn More about Azure Static Web Apps
Learn more about Azure Blob Storage

You can access the source code for this example here on GitHub: videlalvaro/upload_image.

Azure Functions with WSL2 and Visual Studio Code

Alvaro Videla — Thu, 13 Aug 2020 23:47:49 +0000

When executing Visual Studio Code through WSL2 we might find some problems when running Azure Functions locally. While those problems are easy to fix, they might leave you puzzled trying to find the solutions for them. In this article we'll look into that.

Azure Functions Core Tools are not installed

Once you have an Azure Functions project on Visual Studio Code, you might want to run it locally for debugging it by pressing F5. Here's an error you might encounter:

You must have Azure Functions Core Tools installed to debug your local functions

So the problem here is clearly that we don't have Azure Functions Core Tools, now the question is where to install it.

Since we are running Visual Studio Code from WSL2 we need to install the Azure Functions Core Tools on the WSL2 side. Installing them on Windows 10 won't solve this issue.

Here's how to install them on Ubuntu 18.04:



wget -q https://packages.microsoft.com/config/ubuntu/18.04/packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb

For a full set of installation instructions take a look to this article Work with Azure Functions Core Tools

Could not connect to debug target

The second problem I've found was Visual Studio Code telling me it wasn't able to attach the debugger:

In this case my problem was that while I did have node.js installed, I didn't have the supported version which is v12. Here's how to solve that problem:



npm install -g n
n lts

n is a program that you can use to install various versions of node.js on your system. As of this writing the LTS version (12.18.3) is the one we want, so by running n lts we can get that version running on our system.

And that's it! Two very quick solutions for problems you might find when running Azure Functions locally on WSL2 on Windows 10. Until next time!

How to bridge RabbitMQ with Service Bus

Alvaro Videla — Mon, 22 Jun 2020 23:43:48 +0000

In this article we are going to learn how to send messages from RabbitMQ to Azure Service Bus.

Here's a few scenarios in which we can make use of these capabilities:

Edge Setups: We have an edge setup where we are sending messages to RabbitMQ, but we want to forward those messages to Azure Service Bus for further processing, so we can use many of the Azure Big Data capabilities.
Hybrid Cloud: Your company just acquired a third party that uses RabbitMQ for their messaging needs. They are on a different cloud. While they transition to Azure you can already start sharing data by bridging RabbitMQ with Service Bus.
Third Party Integration: A third party uses RabbitMQ as a broker, and wants to send their data to us, but they are outside our organization. We can provide them with SAS Key giving them access to a limited set of Service Bus queues where they can forward their messages to.

The list goes on, but we can solve most of these use cases by bridging RabbitMQ to Azure.

First you need to create a free Azure account by signing up here

Once you are signed in to your account go to the azure portal and create a new Service Bus namespace. Namespaces are the scoping containers where our messaging components will live, like queues and topics.

Adding a new Service Bus Namespace

In Azure Portal click the big plus button to add a new resource

Then select Integration and click on Service Bus to create a messaging namespace:

You will be prompted to enter the information for the namespace. So first select the Azure subscription you want to use, and create a new resource group if you don't have one already (more on resource groups here).

For Namespace name you can use rabbitmq but it could be anything you want. Then set East US for the location, and in this case take the Basic price tier.

If all went well you should see the following confirmation screen:

Then back at the Azure Portal you'll see your new rabbitmq namespace listed there. Click on it to access the resource so you can add a queue to it.

Creating our Service Bus Queue

Now that you have your service bus namespace, click on the Queues button on the left, under Entities, so you can add a new queue:

The name of the queue will be from-rabbitmq just as a reminder to where are the messages coming from. You can leave all the other options as defaults, but of course you can change them to fit the needs of your app.

Enabling the RabbitMQ Shovel Plugin

To ship messages from RabbitMQ to Azure Service Bus we are going to use the Shovel Plugin that comes packaged with RabbitMQ. You can enable it with the following command (you might need to run this command with administrator privileges or via the rabbitmq user):

rabbitmq-plugins enable rabbitmq_shovel_management

Actually that command enables the visual interface for the plugin, which ends up enabling the shovel plugin for us.

Now is time to get the credentials required for connecting RabbitMQ to Azure.

Connecting RabbitMQ to Azure Service Bus

You'll need to create a Shared Access Policy (SAS) for your queue, so RabbitMQ can publish messages to it. A SAS Policy will allow us to specify how much an external party can do with our resource. In this case the idea is that RabbitMQ is just able to send messages, but not listen to the queue, or to manage the queue.

So in this case tick the Send box and then click Create to have our SAS Policy in place.

Once the policy has been created click on it to see the Primary Connection String which is what you are going to use to let RabbitMQ talk to Azure Service Bus:

Before you can use that connection string, you'll need to convert it to RabbitMQ's AMQP connection format. I created a basic website to ease that process. So go here and paste your connection string in the form, click convert, and you will get a connection string that is RabbitMQ ready. (Don't worry, that website runs everything in your browser so your data is safe). If you wanna be sure, the source code is on GitHub.

Now open the RabbitMQ management plugin in our browsers http://localhost:15672/#/dynamic-shovels and go to Admin -> Shovel Management, where you can add your new shovel that will take care of sending messages from a RabbitMQ queue to your Azure Service Bus queue.

Here name your shovel azure and choose AMQP 0.9.1 as the source protocol. This tells the shovel plugin how to connect to your local RabbitMQ server. In the screenshot we have amqp:// which is the default URI that connects us to a local RabbitMQ server. Make sure to adapt that to your current deployment.

On the queue side of things, specify the name of your queue. In this case I used azure which is the name of a queue that I had already created in RabbitMQ. If you don't have that queue you can create it on the RabbitMQ management plugin, under the Queues tab. You can leave the other options as default.

Then on the destination side of things, we are going to choose AMQP 1.0 as the protocol. In the URI field we'll enter the connecting string that we got from the previous step that converted our Azure connection string to our RabbitMQ format. It should look like this:

amqps://rabbitmq-shovel:StringOfRandomChars@rabbitmq.servicebus.windows.net:5671/?sasl=plain

In the Address field we'll enter the name of our Service Bus Queue, in this case, it was called from-rabbitmq. Click Add Shovel, and our set up should be ready to start receiving messages.

Publishing Messages from RabbitMQ to Azure Service Bus

In the RabbitMQ Management interface we can go to Queues, select the azure queue, and search for the Publish message panel. There a form will appear that will let you publish messages directly to our queue. For our example we are just going to add fist message as the Payload and hit Publish Message:

Go back to Azure and inspect your queue. Click Service Bus Explorer in the left panel. If all went well you'll see your queue now has one message. Yay, congrats!

But let's make sure that message is the one you sent from RabbitMQ. Select the Peek tab and click the Peek button to retrieve the last messages in your queue. Click on the message to inspect its contents. You should see something like the image below where your first message is listed.

Let's Recap

Congrats! We did a lot and we managed to get our messages from RabbitMQ to Azure Service Bus, let's recap the steps:

Create an Azure Service Bus Namespace
Add a queue to the namespace
Add a SAS Policy to our queue
Get the queue connection string
Enable the RabbitMQ shovel plugin & the management interface
Convert the Azure Service Bus connection string to RabbitMQ's AMQP format
Add a new shovel to RabbitMQ
Publish messages

By following the previous steps you were able to integrate areas of your org that might be outside of Azure, by shipping messages from RabbitMQ to Azure Service Bus using the Shovel Plugin. This has enormous advantages since we can even allow trusted third parties to connect their apps with our Azure deployment.

In the end, messaging is about enabling connections, and with this technique we just opened a new one.

Como agregar un corazón verde 💚 al prompt de tu Terminal

Alvaro Videla — Thu, 18 Jun 2020 13:07:30 +0000

En este pequeño artículo les quiero mostrar como customizar el prompt de su terminal para que muestre un corazón verde 💚.

Primero dependiendo del sistema en que trabajemos (Mac, Ubuntu, etc.), vamos a tener que editar ya sea el archivo .bashrc, o .bashprofile.

Allí vamos a editar la variable PS1 que es la que controla como luce el prompt. Como puede haber varias de ellas, vamos a identificar cuál es la que afecta nuestro setup.

Para ello en la terminal, podemos ejecutar el siguiente comando echo $PS1 que nos va a mostrar el contenido de la variable:

Luego vamos al archivo de configuración y allí modificamos nuestra vairable PS1, agregando el corazón verde 💚 donde más nos guste:

Y luego si abrimos una nueva terminal va a lucir de este modo:

Notional Machines and The Karl Hassan Question

Alvaro Videla — Mon, 04 May 2020 18:04:53 +0000

In the article Thinking out of the box: comparing metaphors for variables in programming education, by Hermans et al., they present a study that compares the effectiveness of metaphors when teaching novices about programming variables. For their study, they used two metaphors: variables as a box, and variables as labels that one can place on one value. So the box metaphors leads to x contains 5, while the label metaphors leads to x is 5.

Once the subjects had their basic programming lessons, they were asked questions to test their understanding. Using Scratch as programming language, the researchers asked questions about the results of a program, and also asked people for explanation of their reasoning:

set points to 0
set points to 2

Question: What is stored in points now?

In that case, some people arrived at the right answer, but their reasoning was wrong. While 2 is the right answer, justifying it by saying that 0 + 2 = 2 is not the right reasoning. This problem with mutation is discussed in Joe Armstrong's book Programming Erlang. There he explains how by having a single assignment of variables, Erlang is more familiar to the math one learns in school.

A more interesting example happens when they asked people to reason about strings and variables:

set name to Karl
set name to Hassan

Question: What is stored in name?

Some people answered KarlHassan, while others replied KarlSan. I want to focus on the latter, since the authors consider this reply to be a misconception.

Earlier in the paper the authors mention the idea of a "Notional Machine", which is explained as:

the general properties that a student assumes of the machine executing their code. It involves various aspects related to the program: compiler, memory management, etc. Having an incorrect understanding of the notional machine of a programming language is believed to be the cause of many misconceptions.

I think this idea of notional machine is critical when it comes to understanding if KarlSan qualifies as a misconception. To speak of a misconception, means that there is a correct answer according to some notional machine. Subjects received basic programming lessons, which are not included in the paper, so it's not clear in the paper if the researchers shared their own (correct?) notional machine with their subjects.

Code executes in a particular context, and there are contexts for which KarlSan is a correct answer.

Let's talk about Java, and its Non-Atomic Treatment of double and long. As Goetz explains in Java Concurrency in Practice, the JVM could "treat a 64-bit read and write as two separate 32-bit operations." In a multithreaded environment, it's possible to read 32 bits of one value, and 32 bits of another! Transposing this to our example, there's a notional machine for which KarlSan is the right answer. We could easily create such a scenario with an hypothetical 8 bit computer, where unless the programming language updates strings of bytes atomically, there would be no guarantee that KarlSan wouldn't happen.

Without a shared notional machine, it's hard to evaluate the subject's answers--KarlSan--as invalid or "misconceptions".

Overwriting data metaphor

In section 5.3 of the papers the authors write:

we observed that participants often tried to calculate with the given values in Q7, i.e. adding 0 and 2 together, rather than understanding that 2 overwrites the existing value 0. [emphasis mine]

The word overwrite is very interesting because it's a metaphor that semantically departs from the notion of variables as labels or variables as boxes. Would it be better to explain variable assignment as "overwriting" sectors of memory?

Metaphors and Notional Machines

A quick note on notional machines. In So… what is a notional machine? Hermans talks of these devices as being scaffolding that help us understand other ideas. How close is this to Lakoff's & Núñez idea of metaphorical scaffolding, as presented in their book Where Mathematics Comes From?

When explaining concepts like Sets, the line number (another metaphor), and so on, they say that we understand Sets (or any other mathematical concept), because we have built over the years a scaffolding of metaphors that finally let us support the idea of a Set. It'd be interesting to perform a similar exercise for programming, selecting one programming language and going over the many metaphors that help us understand what a function does, or what a loop does, and so on.

while(feedback) learn

Another question for the study is to ask if a one shot exam is a good measurement for understanding which metaphor is better, the box one or the label one. Because learning is not a one shot opportunity. We learn through feedback, by applying what we have learnt, even if through a misconception, and then later receiving correcting nudges that put us in the right direction. In the long run, which metaphor is actually better?

Another question is embodiment. Certain metaphors make sense due to our past experiences, our own body, our abilities, our culture, mother language, and so on. While it's clear that the study was targeted at either Dutch or English speakers, it’d be interesting to find out which metaphors work better in other cultures, like in Chinese or Ewe. In Fundamentals of Comparative And Intercultural Philosophy, Ma and Van Brakel explain how the concept of "to be" is divided among several verbs in the African language Ewe. How would this affect the idea of variable assignment, and which metaphors would be more apt in such cases?

Due to embodiment, objects present us with affordances--clues that tell us how an object can be used. In Vision in Design, Hekkert and van Dijk explain that a ceiling is a place to hang things from, like lightbulbs, but not a place to walk. Not for a fly though, for them a ceiling is a walking surface. “What is the purpose of a pen for someone who has lost his hands? Is it still a ‘tool for writing’?”.

In the same vein we can ask which life experiences, abilities, cultural background, and so on, make a box or a label more fit as metaphors.

Conclusion

The paper by Hermans definitely opens some interesting questions, from metaphors to the rightness of notional machines. Sharing notional machines seems to be a precondition for evaluating the effectiveness of metaphors, perhaps to the point where finding Lakoff's scaffolding for programming could be a crucial development to reason about how to best teach and learn programming. When discussing the rightness of metaphors, it would be interesting to be one the lookout for metaphors that might pop up when explaining concepts, like the overwrite metaphor presented above. Perhaps that was the right metaphor all along?

The Code Speaks On Its Own, NOT

Alvaro Videla — Thu, 23 Apr 2020 17:33:00 +0000

If we receive a letter saying: "you must stay home, you can only go out for grocery shopping", we won't just follow it, first we'll check who sent it. If it comes from an authority, then we'll follow its orders.

To interpret a text we need to see its context, and context is provided not by the text itself, but by things that surround it: book titles, publisher's info, jacket copy, author, date published (april's fool anyone?), and so on. In Literary Theory, these devices are called paratexts.

Paratexts are key elements when it comes to interpreting a text, to understanding as a reader how we are supposed to use and interpret the text. They guide us as we find meaning. We need paratexts, because text doesn't speak on its own. To interpret it we need context.

Code works the same. We have comments, type declarations, package names, compiler flags, and many more things that provide clues on how to interpret the code, because code on its own doesn't speak for itself.

Let's see some examples from Visual Studio Code to understand how context is important when reading code.

The two classes that were almost the same

Let's take a look at the class OpenIssueReporterArgs, which appears twice in VSC. The first time inside the file vscode/src/vs/workbench/contrib/issue/common/commands.ts:

export interface OpenIssueReporterArgs {
    readonly extensionId?: string;
    readonly issueTitle?: string;
    readonly issueBody?: string;
}

and the second one inside the file vscode/src/vs/workbench/api/common/apiCommands.ts:

export interface OpenIssueReporterArgs {
    readonly extensionId: string;
    readonly issueTitle?: string;
    readonly issueBody?: string;
}

These interfaces are used by the Issue Reporter Tool (see image), they specify the interface for the arguments passed to the tool. The interfaces are almost identical, the only difference being that in the second interface extensionId is required. So how do we know what they do? They don't seem to be speaking too much on their own, do they?

Remember we said package names act as paratext, they can help us interpret code by providing context? In this case our first interface lives inside vscode/src/vs/workbench/contrib, while the second one is inside vscode/src/vs/workbench/api. Inside contrib we have contributions that add features to VSC like full text search or git. One of those contributions is the Issue Reporter Tool. These contributions can be used from VSC, while the second one is inside api, which can be used by extensions. Extensions must provide their ID when reporting issues, while VSC doesn't need to do that. That's why for the apiCommands version of OpenIssueReporterArgs the parameter extensionId is required.

Code Comments are Hard

Another place where we see paratexts is in code comments. An evergreen problem with comments is that they tend to lose touch with code, falling behind from actual features, or even commenting about stuff that's not there anymore. But don't worry, we aren't the only ones with this problem. Not even Cervantes escaped this fate: in Don Quixote, the description for Chapter X doesn’t match the contents of the chapter. When they reformatted the book, the chapter description stopped matching its contents.

In the case of Visual Studio Code, it has some great docs for its APIs, detailing what a function is doing, the expected types and so on. But even there, we might find things that are confusing. Take a look at this code from vscode/src/vs/base/common/collections.ts:

/**
 * Returns an array which contains all values that reside
 * in the given set.`
 */
export function values<T>(from: IStringDictionary<T> | INumberDictionary<T>): T[] {
    const result: T[] = [];
    for (let key in from) {
        if (hasOwnProperty.call(from, key)) {
            result.push((from as any)[key]);
        }
    }
    return result;
}

The docs talk about a set, while the function accepts a dictionary. In my article Metaphors We Compute By I discuss how names are important because they augment the understanding we have of situations, or in this case, of pieces of code. A set implies uniqueness of elements. Moreover, a set offers certain operations like intersection, union, and so on, that is not clear at first sight how they would make sense for a dictionary, if at all.

So I opened a PR, updating the comments for those functions. While I was doing the final commit, I realized that there were more functions inside that API that mentioned set instead of dictionary. Again, keeping docs & comments in sync is hard. I think having just one function fixed saying dictionary while the others said set would have been even worse, since a future reader might be led to think they do different things.

About this issue, a colleague introduced me to a couple of tools that could help with this. One of them is electron/docs-parser. Then we have electron/typescript-definitions, and finally electron/archaeologist.

With docs-parser they generate an AST out of the documentation found in their TypeScript code. Then that AST is used by typescript-definitions to output actual TypeScript types. Finally with archaeologist they make sure that whenever a pull request is submitted against Electron, the types as they appear in the functions, match the types described in the docs. For all this to work, Electron developers have to follow a documentation style guide. I think this is a step in the right direction.

Conclusion

In this article we showed how "code speaks on its own" is just a myth. All texts, including code, work because they are assisted by many devices that help us interpret them. In Literary Theory, some of those devices are called paratexts. We saw paratexts appear in code in the shape of comments, types, package names and so on.

We saw how to understand an interface that was almost identical with another one, we had to resort to package names to understand its purpose.

Finally about comments we learnt that as with Don Quixote, we need to make sure our paratexts match the content they are trying to describe, otherwise they just add confusion. In the case of comments matching code, we saw that the people behind Electron are creating tools that move us forward in the right direction.

Inside Visual Studio Code - Classes and Interfaces

Alvaro Videla — Thu, 02 Apr 2020 15:38:27 +0000

I've been trying to dive into the internals of Visual Studio Code, so I wanted to have a tool that would let me see the names of classes and interfaces declared in VSC own code.

This tool would traverse VSC own code, load the TypeScript files defined there, and then for each file it would output something like this:

ColorPickerBody|/path/to/vscode/src/vs/editor/contrib/colorPicker/colorPickerWidget.ts
ColorPickerHeader|/path/to/vscode/src/vs/editor/contrib/colorPicker/colorPickerWidget.ts

Where ColorPickerBody and ColorPickerHeader are two classes defined inside colorPickerWidget.ts.

Yesterday I asked on Twitter if someone knew about a tool that could extract this information from a TypeScript file. Someone recommended that I use ts-morph, which after taking a look at the examples on their docs, seemed to do just what I wanted.

So I started a new TypeScript project, npm'ed ts-morph and then built something like this:

import { Project, ClassDeclaration, InterfaceDeclaration } from "ts-morph";

const project = new Project();
project.addSourceFilesAtPaths("../vscode/src/vs/**/*.ts");

const sourceFiles = project.getSourceFiles();

for (let f of sourceFiles) {
    let fileName = f.getFilePath();
    let classDeclarations = f.getClasses();
    let interfaceDeclarations = f.getInterfaces();

    for (let c of classDeclarations) {
        console.log(`${c.getName()}|${fileName}`);
    }

    for (let i of interfaceDeclarations) {
        console.log(`${i.getName()}|${fileName}`);
    }
}

Let's see that in detail. First we import the required types from ts-morph:

import { Project, ClassDeclaration, InterfaceDeclaration } from "ts-morph";

Then we create a new project, and we add source files to it. In this case we asume the location of the VSC repo–of course you could provide this as a CLI argument.

const project = new Project();
project.addSourceFilesAtPaths("../vscode/src/vs/**/*.ts");

We are going to traverse those files to extract class and interface definitions. We do that by calling project.getSourceFiles(), which returns an array of SourceFile. SourceFile is a class that can return a lot of information about a TypeScript file, from it's file name, to the imports declared there, and so on.

Once we have the SourceFiles[] we are going to iterate it, to output the information we need:

for (let f of sourceFiles) {
    let fileName = f.getFilePath();
    let classDeclarations = f.getClasses();
    let interfaceDeclarations = f.getInterfaces();

    for (let c of classDeclarations) {
        console.log(`${c.getName()}|${fileName}`);
    }

    for (let i of interfaceDeclarations) {
        console.log(`${i.getName()}|${fileName}`);
    }
}

As you can see each SourceFile can tell us about its name, via f.getFilePath(), and also return the declared classes and interfaces via f.getClasses() and f.getInterfaces() respectively.

We use two for loops, where we output the information in the following format: className|fileName, or interfaceName|fileName.

And that's it, after we compile the project, we can run it from the CLI and get the information we want:

IStaticExtension|/path/to/vscode/src/vs/workbench/workbench.web.api.ts
ICommontTelemetryPropertiesResolver|/path/to/vscode/src/vs/workbench/workbench.web.api.ts
IExternalUriResolver|/path/to/vscode/src/vs/workbench/workbench.web.api.ts
TunnelOptions|/path/to/vscode/src/vs/workbench/workbench.web.api.ts

You might have been wondering why I want the information output in that format. I want to be able to pass this file to bash's sort and have an easy way to see which class & interface definition name are repeated across the project.

Why? Soon I'll write another article explaining why.