Forem: Kiru

Unconventional Programming Opinion: You become an unofficial maintainer once you update your framewor

Kiru — Fri, 09 Jun 2023 11:40:40 +0000

TLDR: Dear framework developer, please consider us, the framework users, as the unofficial maintainer of your framework. When you change things, think about the wider cost.

Warning: This is going to be a short gibberish, brain-fart and/or rant.

Recently I was migrating a project from a framework v385 to v366 and felt the pain wasting time to apply some internal refactoring the framework team did to my own project.

Imagine if I had the following functions in my code and I wanted to refactor.

const isUnicorn = (animal) => {
  return hornCheck(animal)
        && !isThisCodeImaginary(animal)
        && areWeInMysticalLand();
}
const hornCheck = (animal) => animal.horns.length == 1;
const isThisCodeImaginary = (animal) => 1/0;
const areWeInMysticalLand = () => true;

Renaming any of those functions would cost me nothing. Now, if the same code was a framework, and your users defined the areWeInMysticalLand function, then changing it would be easy for you. For the users, you would leave an entry in the migration notes.

As a developer and user of the before-mentioned imaginary framework, you literally are changing your code to satisfy the refactoring the framework developers did.

Obviously this is a made up example and I don’t want to point the fingers to the poor maintainers. I just want to give you a different perspective on how to think about small changes.

With each new version of frameworks, languages, and tools around us, I wonder, when do we stop doing stuff in the name of better and improvements.

That’s it?
Yep, I don’t want to waste your and my time.

Let me go back searching the internet for why v366 gives me an error.

See ya later.

Unconventional Programming Tips: Search Better

Kiru — Mon, 06 Feb 2023 09:19:36 +0000

Originally posted on my personal blog

Who is this for?

This article is mainly intended for programmer.
If you frequently search for code snippets in your code base, then this article is for you.

How I used to search

One of the most common tasks when I code is not actually writing or reading code,
but rather looking for something. I have a code base and want to find the following function:

function isSign(firstNumber0: NumberPad | null) {
  return firstNumber0 == NumberPad.PLUS || firstNumber0 == NumberPad.MINUS;
}

I could search for function isSign or isSign to find the above function.
Both would yield the expected results.
Though, In many cases you would end up with many more unrelated results as well, and have to filter them by hand:

I am using rg for demonstration purposes. The searches are mostly done in a decent IDE.

What changed

Once I was working on a python project and was frequently searching for functions.
Remember, python functions are like def myFunction().
A team member (🙏 Florian) pointed out,
that I could just look for f myFunction. That was tiny hint, but then,
I have been using that technique for almost daily.

How I search now

To find the above function, you could look for n isSign or even shorter terms are n i or Sign(.

The general rule is: If you want to search better, then look for the most uncommon part of the search term.

This trick works even better with HTML. For example, on this blog,
I want to find where the menu is defined. There is a TIL item, so in the source code, there must be a tag like <a>TIL</a>.

In those cases, I made a habit of looking for TIL<. That way, I don't see all the noisy content where TIL is
defined in comments or text.

Once you start frequently using this technique,
you start immediately spotting what is common (in your code base) and what is uncommon.

This tip is not limited to code. You want to find any text, then train yourself (by experience) to the uncommonness:

Thank you!

Thank you for reading the full article ! If you learned something new,
you may find my unconventional tips for coding comments interesting as well.

Unconventional Programming Tips: Comments

Kiru — Thu, 18 Nov 2021 14:48:01 +0000

Originally posted on my personal blog.

Random thoughts on programming

I was recently reading Best Practices for writing code comments by Ellen Spertus.
While there are some helpful tips, it misses the most important ones for me:

Add "why" comments when you write the code.
Add all the other comments when you read the code.

What is the main purpose of comments?
They should help me understand the code easier. More than often, when I write the code, it is immediately clear what I was trying to solve. I have the context and the reason for my decisions are freshly in my mind.

Few days later, re-reading the code, I don't know anymore why I wrote the code like that. That is when I add the most valuable comments. Many people tell you not to duplicate code with comments, but if it makes it easier to understand the code - why not? Don't follow any advices blindly - even the above ones.

Consider this example:

while (element.parentElement != null){
   // do some stufff
}

while (element.parentElement != null){ // we didn't reach root
   // do some stufff
}

On a daily basis, I don't tend to write many while loops. That makes while loops not always easy to grasp. If I encounter one, it is not very easy to understand the conditions. In the above case, the condition is simple, nevertheless the added comment improves the code quality for me. I don't have to focus on the condition, I can read the inner parts knowing they are executed until we reach the root.

In many cases, null checks are another good example. Null has so many semantics, while I write the code, I know the meaning of a variable being null, but when I read it again, it is not clear what the initial reason was:

is it because null means the value has not been set?
is it because null means the value was there, but has not been set?
is it because null means the value is invalid?
is null the expected value?

Try to add a comment why you expect null. You don't have to add it each time - only in the cases where it is not clear from reading the code.

TLDR: Best comments are written when you read the code - not when you write it.