A small contribution to curl

The venerable curl is one of the most fundamental pieces of code in the modern world. A seemingly simply utility - it enables other programs to interact with URls - it runs on millions of cars, is inside nearly every TV, used by billions of people, and is even in use on Mars.

And, as of last week, features a small contribution by me!

Look, I'm not an experienced bit-twiddler. I can't micro-optimise algorithms or spot intricate C-based memory leaks. What I can do is get annoyed at poor documentation!

You see, documentation and code comments are vitally important. Poor spelling might trip up non-native speakers, bad examples confuse learners, and ambiguous wording is a barrier to understanding.

As was written by the sages:

a computer language is not just a way of getting a computer to perform operations but rather that it is a novel formal medium for expressing ideas about methodology. Thus, programs must be written for people to read, and only incidentally for machines to execute. Abelson, Sussman, and Sussman Structure and Interpretation of Computer Programs

So, what did I fix? A few years ago, I noticed Google's documentation used example domains it didn't control. The same thing was happening in the curl source code.

One example domain used was "HTTPS://your.favourite.ssl.site" - when that code was written 23 years ago, the .site TLD didn't exist. Now it does.

Is there a serious risk that someone will register ssl.site and use it to take over the machine of anyone who unthinkingly follows that example? Probably not. But it also isn't terribly clear that it is an example. So I changed it to secure.site.example which uses the reserved .example TLD.

That should make it clear to everyone that it is a placeholder example and will prevent anyone from misusing that domain.

Similarly, there were a few comments which used domain.com as an example. However, that's a real website - so I updated those to example.com.

I was delighted to see the changes accepted.

And I was only slightly disappointed to have narrowly missed out on being contributor 1337, but being number 1342 ain't so bad 😄

You can see the full list of changes on GitHub.

Much like my patch to the Linux Kernel this might be considered a trivial matter - but I honestly believe that clear and accurate documentation can be as important as the code itself.

Huge thanks to Daniel for creating curl, for making such a welcoming environment for new contributors, and for handing out such brilliant stickers at FOSDEM!