When I started to learn to code for real my second real-life learning project was a text editor. Like all those editor examples I started with a basic notepad and then added I/O functionality and then stuff like font/color settings. In that summer, I made it to a full featured text editor with a multi-panel editor, a built-in calculator, command line to work and even used some tools to load ePub / PDF. I was really proud of it; it was my successful summer project.

When I showed it to our computer teacher he said one thing that I never ever forgot:

These words stuck with me forever. I was so offended and angry. Didn’t even know what clean code was but I didn’t like my creation to be told “a mess”. My journey started somewhere in that day…

What is a clean code by definition?

I started crawling the web on what is clean code. And it turned out to be many things. Thousands of tips fell of the sky on what is clean & good code:

• You should apply all sorts of methodologies like KISS, DRY, YAGNI.
• You should apply structure and good design to the code. (Great classing and hierarchies, good design-patters et cetera).
• It should be written for another developer so that the developer could read it easily.
• You should use the right language.
• There should exist blueprints for the application (LDM, CDM, Sequence Diagrams, Entity Diagrams, Activity Diagrams, Class Diagrams, ER and many many more.)
• Your code should be extendable.
• Good public API design.
• It must be easy to understand an element’s responsibility in your code.

This is no wonder that it took me years to learn all of these and apply it to my codes. Yet, after all of them: I still hated my codes. Not just my codes per say, everyone’s codes. I was obsessed with clarity and I wanted to see a clean, beautiful code so much that it hurt.

Pushing the barriers, Step 1: Coding Style

First thing I noticed on the clean code was the coding style. Codes must be easy to read and by easy I mean as less effort as possible.

Let me show you a good example of that. This is a part of the Roslyn Compiler. If we agree on the fact that Microsoft is one of the world’s best software development companies then we can agree that Roslyn (the compiler for C# which is the infrastructure of Microsoft) is one of the most important projects of the company and therefore

If you focus correctly, you see that actually reading this code snippet is actually darn hard. Line heights are so tense and there are long names with a compressed look. It’s actually frustrating to read codes like this (and this is a great code so something here is wrong)

My first change in this journey was to improve the code by applying more spacings, this way there could be more of negative space to help the brain read easier.

f(g(h(j(x))))

And then you could have written that as:

j(x) -> h -> g -> f

It looks horrible right? No! it does not! It’s because we have a very big font size and so much of negative space in my blog. But what if we look at a code in its actual font size?

See? The coding style actually worked! This is what we call Kary Foundation Coding Standards or KFCS.

For KFCS I developed a TypeScript/JavaScript formatter called Righteous which now has a plugin for Visual Studio Code, so even coding this way is not hard because you write your code and click on the formatter to make it pretty.

Step 2: Kary Comment , Brining Richness of Design into Code

I started to experiment with a software to generate comments. Comments are the core of the decoration in our daily system. We use them to inform about the stuff that happens in our code bases but we also use them to make the code pretty. When I was making the Comment software I thought:

Then I began to write a “comment generator” which is a software that you use to generate “decorative comments”. After I experimented with this new methodology in production on HeatStudio (which is a giant governmental project) and I understood the potential these decorative organizing comments.

![10rem](my-two-years-journey-into-clean-code/04.png" style=“max-width: 626px;”>

These comments help you manage and organize your code. I made a specification on how this comments could be used and what’s the standard you can adapt to shape your codes with style and organization.

After that I developed many Kary-comment generator software:

• Comment IV — The online version
• Comment for Visual Studio Code — Which without ever being advertised has 3K installs in the time being
• Kary Graph — We support comment natively in Kary Graph
• And much more…

Step 3: We need colors

Everything was great by then. I had a system that was so readable and beautiful. You could just sit and enjoy reading codes. Yet, there was a problem. Have you ever seen a software developer and their codes? Their workspace looks horrible.

There’s an unwritten rule in engineering that everything needs to just work and not be pretty. It’s like if you do something that makes you more efficient then that’s great but something that makes your workspace a bit more pretty is just waste of time. This is an attitude that I hate that so much, I feel it in my stomach.

Why is coding not pretty? Because we just try to look like hackers. Who are hackers? These guys:

While it actually could be pretty and stylish like as in the Her movie:

In that respect, I designed a color theme. One with a big change: It had to be no ordinary theme, It needed to be soft, pretty, stylish and like candy not like rock. I tried color schemes and experimented a lot till I ended up with Kary Foundation Themes which at the time being, has more than 12K installs on Visual Studio Code’s market place and is regarded as one of it’s most popular themes.

The theme solved so much. It changed the whole look of your workspace so you no longer felt like a robot without emotions that sits behind a theme like Monokai but rather someone with feelings and understanding of beauty. You can’t use that theme and write crappy codes.

Orchestra Language

Next stop in my journey was Regular Expressions and when I met some real examples of it. My job most of the times was working on compilers and stuff that used the same practice so RegExps are one of the best tools I use every day. But their syntax has always being a pain-in-the-ass literally. Look at these:

• (?<!\\.|\\$)(?:(\\bexport)\\s+)?\\b(var|let|const(?!\\s+enum\\b))\\b(?!\\$)
• (?=$|;|}|(\\s+(of|in)\\s+)) -(?x)([_$[:alpha:]][_$[:alnum:]]*)(?=\\s*\n (=\\s*(\n (async\\s+) |\n (function\\s*[(<]) |\n (function\\s+) |\n ([_$[:alpha:]][_$[:alnum:]]*\\s*=>) |\n ([(]\\s*(([)]\\s*:)|([_$[:alpha:]][_$[:alnum:]]*\\s*:)|(\\.\\.\\.) )) |\n ([<]\\s*[_$[:alpha:]][_$[:alnum:]]*((\\s+extends\\s*[^=>])|(\\s*[,]))) |\n ((<([^<>]|\\<[^<>]+\\>)+>\\s*)?\\(([^()]|\\([^()]*\\))*\\)(\\s*:\\s*(.)*)?\\s*=>))\n ) |\n (:\\s*(\n (<) |\n ([(]\\s*(\n ([)]) |\n (\\.\\.\\.) |\n ([_$[:alnum:]]+\\s*(\n ([:,?=])|\n ([)]\\s*=>)\n ))\n )))\n )\n)
• (?=$|[;,=}]|(\\s+(of|in)\\s+))
• ([[:upper:]][_$[:digit:][:upper:]]*)(?![_$[:alnum:]])
• (?=(([_$[:alpha:]][_$[:alnum:]]*)|(\\'[^']*\\')|(\\\"[^\"]*\\\")|(\\[([^\\[\\]]|\\[[^\\[\\]]*\\])+\\]))\\s*(:))
• (?=(([_$[:alpha:]][_$[:alnum:]]*)|(\\'[^']*\\')|(\\\"[^\"]*\\\")|(\\[([^\\[\\]]|\\[[^\\[\\]]*\\])+\\]))\\s*(:))
• (?<!\\.|\\$)(?:(\\bexport)\\s+)?\\b(type)\\b\\s+([_$[:alpha:]][_$[:alnum:]]*)\\s*

These are some randomly chosen RegExps from Visual Studio Code’s JavaScript Language Definition. Unlike our programming languages that have been evolved in the past 40~50 years. RegExps remained as ugly as it was in the first place. I tried to ignore my expectations and be okay with it but I couldn’t and I found that I have to make a replacement for RegExps.

Finding the cure…

My first attempt was making a library out of RegExps and that turned out to be stupidly slow when typing. Then I thought about another textual language and after some iterations of prototyping, I once again found myself miserably in the non-comfortable zone. When every door that I tried to open was stupidly locked I found the crazy remaining option: a “Visual” language.

Orchestra Language is a simple syntax for RegExp that compiles to standard RegExp code and makes it easy to read/write real-scale and massive-scale RegExps without pain.

For Orchestra Language I developed two compilers to compile from Orchestra Language to RegExp and from RegExp to Orchestra Language . This way you could write code and edit existing code in Orchestra Language

The beauty of this language was the scale that I could write with it. KaryScript , as well as Orchestra Language itself, are written with Orchestra Language code inside them. You just won’t believe the scale that is possible to reach with this Orchestra Language . And funny is now the only power of Orchestra Language is its readability which means the power and scalability of it is just a result of readability and clean code.

KaryScript

Whatever I did was writing supporting tools and developing workarounds for languages that I used and it didn’t fully help. A revolution was needed. I needed a new language that was readable. Thanks to the modern days, my revolution didn’t have to coast so much. I could develop a language that compiled to JavaScript. This was the point where KaryScript was born: The first language only for the sake of readability.

What can you do to improve the current state of programming languages? We’re in the age where we no longer need algorithms and flowcharts. Our languages have become so advanced and so expressive that just start writing code. If we take this as our lead, making a language readable means: Making a language natural so that you could type the way you thought

When breakthrough happens

Why do we have syntax highlighting? This is the question that changed the way I thought about readability. Human languages are far more advanced and far far more complicated than any programming language. So far we don’t need syntax highlighting in a novel. What makes us miserable without syntax highlighting in a code?

The answer I ended up with was so simple that it look silly but it was the answer to what I was looking:

In programming, we don’t. One just jumps all the time from one place to another. It’s not like a novel. In a novel. You open the book and follow words, In programming you don’t.

One finds the starting function and has to jump to the definition of the functions defined within that function and go back and then loop through the for/while loops. One conditionally jumps over the code and that makes it really hard to focus. And that’s exactly why we use syntax highlighting to not read the code and easily jump.

With that said. The main factor in making a language more readable, clean and pleasant is linear thinking. Don’t take it wrong: That’s the biggest factor. My goal with KaryScript was to make it as much as linear as possible.

Pipes

The first thing that I brought to KaryScript was Pipes. In fact, their existence is thanks to linear thinking. Look at the following code:

The eye-flow here is ridiculous. You have to go from fix result to h then g and then f. It’s like reading something written in English/Arabic mix. Going left-to-right and then vise-verse then repeating the process.

We write something entirely different than what goes in our minds. Why do we write like that? The answer comes from the root of our programming languages. First programmers where mathematicians and coding was based on math. In math functions are written like this:

f(x) = x * 2 -> f(2) + 3 = 7

They are nothing more than what we call macros in programming. When you calculate math you expand functions (just like macros and inlining in compilers) and replace the value of it’s inputs inside it. When the function was expanded like this you would start calculating it:

f(2) + 3 -> 2 * 2 + 3

That sucks. In programming, we can do much better. We can say each function a factory (or anything with I/O). Each factory does something and then sends it’s output to another factory. Pipes are made like this. If a function is a factory, the pipe is the heavy truck that moves one factory’s output to another factory’s input:

The beauty here is that the code compiles to the normal function notation. It’s just like a different way of writing the same thing. No memory/performance is sacrificed here and you also can do whatever you could do with the normal notation.

Less Punctuation

When it comes to readability punctuations are evil. They make noise and break our negative spaces. One thing I tried to do was to remove , and .. I replaced the dot notation with slash notation and I adopted the S-Expression style from Lips and removed all ,.

If you look at the object sample from the Table Literals you’ll see there’s no , there. KaryScript is designed in such way that there is no need for , at all.

Table Literals

Complex objects are of the hardest stuff to express and worse enemies of readability. Objects and trees sometimes have more than 2 dimensions that make them really hard to be written and even harder to read them.

This is a simple table containing name and surname of Homer and Marge:

It came across my mind that tables are the most used objects in programming and at the same time I was looking at a Markdown table. With a little bit of thinking I saw no reason why not to have table literals in KaryScript so I brought them to KaryScript and just look how awesome they are:

Tables are one of the most awesome literals I’ve ever seen. When I first met them in markdown I was amazed at how simple and powerful they were.

Kebab-Naming!

When using camelCase or PascalCase one stairs at very complex compressed names that are mostly displayed in like 12~14pt font and that makes it very hard to read and causes the eye an extra pain.

A very pretty and easy to use naming convention is the kebab-naming. It’s simple to write and also very fast to write but very easy to read. KaryScript targets kebab-naming as it’s main way of naming objects:

Expressive Grammar

Many subjects in programming are there but are bad. My favorite is for grammar. I hate everything about it. It’s a horrible grammar. It’s a useless grammar that has bothered everyone when they were starting to code and keeps bothering everyone each time it needs to be written. Just look at it:

And it only means: Repeat something 10 times. We could write that so much better. What I did here was making these grammars as much as possible near to human language. Same thing in KaryScript can be expressed as:

For example, if you wanted to do counter += 2 and use the counter as variable to inform the body of the index, you can write this:

This is much readable grammar, right? It’s clean, pretty and without so much punctuation and ugly stuff. Also, it reads as it does. But more than all that, it enforces repeat in for. You can’t do something like this with it:

If you want to do this, you’ll be forced to use while loop and write it clean not in a compressed for loop.

Holders

Holders are probably stupid and I’ll be having to remove them for good but I’ll keep them to fully test them in the battleground to see if they are worth keeping so don’t blame me or have hope.

Let’s not get ahead of ourselves. What is a holder? To explain it you have to first look at this code:

If we rewrite this with pipes we’ll end up with a problem:

What we do in this situations is to use backup variables like this one to make our codes readable:

These variables are bad for performance and also they take memory if your memory manager is not a high-end one. What can be done in here? Holders are imaginary variables. They look like variables but they are not. They only let you write something in separate parts and KaryScript ’s preprocessor combines them together:

Then it preprocesses to:

It’s like magic. You get to write cleaner code while sacrificing nothing and to make it happen holders have a rule: You can only use a holder once and then they expire. This way they act exactly as variables and they cause no conflict in the code.

But I think this is a very bad practice and not worth being in the language. It can be used very badly like the goto phenomenon.

Grammar for modern JavaScript

JavaScript was never designed for what it’s being used for today. It was a simple silly language for making animations and menus on a website. Today I’ve seen operating systems written in JavaScript. The IDE I’m using right now is made of JavaScript. It’s so powerful and huge that nothing else can be compared to it. With its new weapon WASM, nothing in the whole world can beat it. And that’s it’s problem. It’s becoming dirty over the time because the creators didn’t see what’s going to be added. There simply was no room for new grammar there.

In KaryScript I felt as if we want a clean language we have to redesign it with all the features in mind. For example. When JavaScript was made there was only arrays and objects there. When Set and Map added to the language no literal remained there to be their notation. In KaryScript all 4 structures have literals:

Or for example cloning. One problem with JavaScript is that it’s an all-pointer system and only recently they introduced Object.assign to fix it. KaryScript had to be better in the syntax than using Object.assign. KaryScript now lets you clone an object without sharing it’s pointer, painlessly, boilerplate-free but most of all in a clean respect:

Conclusions

All the efforts I made in the past 2 years was because I wasn’t and I’m still not convinced that programmers are nothing but code generation machines. What public illustrate as the image of a developer is a picture pretty much like Dilbert. Someone with only one dimension of personality, no taste for arts and no taste at all actually, living in junk and hating themselves. This should not be true. Developers are people who create complex structures and give birth to so many wonderful creations. We as the computer society should believe in ourselves and treat ourselves the way we truly deserve not like rocks without soles but like artists with great sense of perfection and taste lie no other.

My research is not finished but only started. KaryScript is it’s in it’s first prototypes and I have big crazy dreams about what I can do to truly transform the way we code to a human-level nature. And at the same time I hope you use what I made and love them the way I do and feel good about your environment and your coding life.

With ☂️, Pouya.