DEV Community: teamradhq

Utility Type: PrependArgs

teamradhq — Tue, 28 Nov 2023 03:12:31 +0000

A utility type to prepend a function's arguments:

type PrependArgs<ArgsToPrepend extends unknown[], T> = T extends (
  ...args: infer Args
) => infer Returns
  ? (...args: [...ArgsToPrepend, ...Args]) => Returns
  : never;

Simply provide an array of arguments to prepend, and the type of the function to extend:

type UpdateUsername = (username: string) => void;
type WithEvent = PrependArgs<[Event<HTMLInputElement>], UpdateUsername>;
// (event: Event<HTMLInputElement>, username: string) => void;

Additionally, we can define a convenience utility to prepend all function arguments on properties of a type:

type PrependPropertyArgs<ArgsToExtend extends unknown[], T> = {
  [K in keyof T]: PrependArgs<ArgsToExtend, T[K]>;
};

This allows us to prepend all arguments on each of type's properties:

type UpdateHandlers = {
  username: (username: string) => void;
  email: (email: string) => void;
  password: (password: string) => void;
};

type UpdateEventHandlers = PrependPropertyArgs<[Event<HTMLInputElement>], UpdateHandlers>

Example: Handling Electron IPC Events

This example uses the WithPrefix utility mentioned previously. In case you missed it, it's a utility for prefixing a type's properties with some value:

export type WithPrefix<Prefix extends string, T, Separator extends string = '/'> = {
  [K in keyof T as `${Prefix}${Separator}${string & K}`]: T[K];
};

Electron apps utilise inter-process communication (IPC) to pass information between main processes and render processes. Typically, an API is defined on the global window that can be used to handle incoming events and initiate outgoing events:

declare global {
  interface Window {
    electron: ElectronAPI;
    api: {
      auth: {
        login: (payload: LoginPayload) => Promise<LoginResponse>;
        logout: () => Promise<boolean>;
        isLoggedIn: () => Promise<boolean>;
      },
      preferences: {
        get: () => Promise<Preferences>;
        set: (payload: Partial<Preferences>) => Promise<Preferences>;
      },
    };
  }
}

Each of the API methods will initiate some kind of event that is sent to the main process:

export const auth: Window['api']['auth'] = {
  async login(payload) {
    return await window.electron.invoke('auth/login', payload);
  },
  async logout() {
    return await window.electron.invoke('auth/logout', payload);
  },
  async isLoggedIn() {
    return await window.electron.invoke('auth/isLoggedIn');
  },
};

On the main process side we would define corresponding handlers:

ipcMain.handle('auth/login', async (event: Electron.IpcMainInvokeEvent, payload: LoginPayload) => {
  return await loginUser(payload);
});

ipcMain.handle('auth/logout', async (event: Electron.IpcMainInvokeEvent) => {
  return await logout();
});

ipcMain.handle('auth/isLoggedIn', async (event: Electron.IpcMainInvokeEvent) => {
  return await isLoggedIn();
});

Typically, we wouldn't want to call our handlers like this. Instead, we would list them somehow and iterate over them to register each handler:

const authHandlers = {
  'auth/login': handleAuthLogin,
  'auth/logout': handleAuthLogout,
  'auth/isLoggedIn': handleAuthIsLoggedIn,
};

for (const [channel, handler] of Object.entries(authHandlers)) {
  ipcMain.handle(channel, handler);
}

This is a nice way to DRY things up. But there are some issues with this approach:

We have no way of knowing whether our implementation covers all of the API methods.
We have to define types for each handler with the only difference being that we prepend an Electron.IpcMainInvokeEvent argument.

We can solve both of these issues with a combination of WithPrefix and PrependPropertyArgs:

type AuthIpcEvents = PrependPropertyArgs<
  [Electron.IpcMainInvokeEvent],
  WithPrefix<'auth', Window['api']['auth']>
>;

WithPrefix<'auth', Window['api']['auth']> prefixes our types
PrependPropertyArgs<[Electron.IpcMainInvokeEvent], T> adds the event parameter as the first argument to each method.

This results in the following type:


type AuthIpcHandlers = {
  'auth/login': (event: Electron.IpcMainInvokeEvent, payload: LoginPayload) => Promise<LoginResponse>;
  'auth/logout': (event: Electron.IpcMainInvokeEvent) => Promise<boolean>,
  'auth/isLoggedIn': (event: Electron.IpcMainInvokeEvent) => Promise<boolean>,
};

Now, if we added an api.auth.register method, we would get a type error:

// TS2741: Property 'auth/register' is missing in type AuthIpcHandlers
const authHandlers = {
  'auth/login': handleAuthLogin,
  'auth/logout': handleAuthLogout,
  'auth/isLoggedIn': handleAuthIsLoggedIn,
};

And our handlers will warn us when we don't provide the event and required arguments:

// TS2554: Expected 2 arguments, but got 1.
const handleLogin: AuthIpcHandlers['auth/login'] = async (payload) => {};

Breaking it down.

This one is relatively simple. We are just defining a new function with our prepended arguments:

type PrependArgs<ArgsToPrepend extends unknown[], T> = T extends (
  ...args: infer Args
) => infer Returns
  ? (...args: [...ArgsToPrepend, ...Args]) => Returns
  : never;

We define generic type ArgsToPrepend extends unknown[] so that we can accept any type.
We state that T must be a function type T extends (...args: infer Args) => infer Returns and also infer the type of its Args and Returns.
We combine our ArgsToPrepend with the inferred Args, resulting in a new function type: (...args: [...ArgsToPrepend, ...Args]) => Returns.
Finally, if we have passed a non-function type, we return never.

Hopefully you find this useful :)

Utility Type: WithPrefix

teamradhq — Mon, 27 Nov 2023 00:53:21 +0000

A utility type for prefixing a type's properties with a string:

export type WithPrefix<Prefix extends string, T, Separator extends string = '/'> = {
  [K in keyof T as `${Prefix}${Separator}${string & K}`]: T[K];
};

Simply provide a prefix, type and optional separator (defaults to /).

type UserApi = {
  get: GetFn<User>;
  set: SetFn<User>;
  all: ListFn<User>;
};

const api: WithPrefix<'/api', UserApi> = {
  '/api/get': getUser,
  '/api/set': setUser,
  '/api/all': listUsers,
};

Example: API routes

When handling interactions between a front-end and back-end we might have an API that looks like this:

type CartApi = {
  checkout: CheckoutFn;
  view: GetFn<Cart>;
  add: PostFn<CartItem | CartItem[]>;
  remove: DeleteFn<CartItem | CartItem[]>;
  update: PatchFn<CartItem | CartItem[]>;
};

To ensure that every API method has a corresponding server route we can use the WithPrefix utility type:

const cartApi: WithPrefix<'/cart', CartApi> = {
  '/cart/checkout': checkout,
  '/cart/view': viewCart,
  '/cart/add': addToCart,
  '/cart/remove': removeFromCart,
  '/cart/update': updateCart,
};

for (const [route, handler] of Object.entries(cartApi)) {
  app[handler.method](route, handler);
}

Whenever we define additional methods on our CartApi:

type CartApi = {
  checkout: CheckoutFn;
  view: GetFn<Cart>;
  add: PostFn<CartItem | CartItem[]>;
  remove: DeleteFn<CartItem | CartItem[]>;
  update: PatchFn<CartItem | CartItem[]>;
  empty: DeleteFn<Cart>;
};

TypeScript will show an error:

// TS2741: Property '/cart/empty' is missing in type WithPrefix<'/cart', CartApi>
const cartApi: WithPrefix<'/cart', CartApi> = {
  '/cart/checkout': checkout,
  '/cart/view': viewCart,
  '/cart/add': addToCart,
  '/cart/remove': removeFromCart,
  '/cart/update': updateCart,
};

Breaking it down

This utility uses mapped types, template literal types and key remapping:

export type WithPrefix<Prefix extends string, T, Separator extends string = '/'> = {
  [K in keyof T as `${Prefix}${Separator}${string & K}`]: T[K];
};

We define a type with:
- A Prefix to add to each property.
- A typeT to prefix.
- ASeparator to separate the prefix from the property name.
We iterate over each property of T and interpolate the prefix and separator with the property name ${Prefix}${Separator}${string & K}.

This gives us a resulting type with our prefixed property names.

Hopefully you find this useful :)

Reference

Utility Type: KeyHasProperties

teamradhq — Wed, 22 Nov 2023 11:20:50 +0000

A utility type creating a union of every key of type that has a specific property:

export type KeysHaveProperty<T, Prop extends string> = {
  [K in keyof T]: Prop extends keyof T[K] ? K : never;
}[keyof T];

Simply provide a type and a property name and we get all keys of that type that have a property with that name.

type ProductStore = {
  clothing: Store<HasVariation>;
  sporting: Store<HasVariation>;
  entertainment: Store<NoVariation>;
}

type ProductKeyWithVariation = KeysHaveProperty<
  ProductStore, 
  'variation'
>; // 'clothing' | 'sporting'

Example: Dynamic Redux Selectors

Recently, I was working with a Redux store which had a number of collections whose state included:

type CollectionState<Item> = {
  all: Item[];
  current: Item;
};

I wanted to define a dynamic selector that I could provide a store slice name and get all of the collection items like this:

const items = useAppSelector(selectAllItems('cart'));

Defining the selector is relatively simple:

function selectAllItems<K extends keyof RootState>(collection: K) {
  return (state: RootState): RootState[K]['all'] => {
    state[collection].all
  };
}

This works just fine if every slice in your store has an all property. But it will show a lot of errors if any slice doesn't have it:

type RootState = {
  products: CollectionState<Product>;
  cart: CollectionState<CartItem> & CartSummary;
  settings: Record<'app' | 'checkout' | 'email', Preferences>
}

This RootState will show a number of errors, and they can feel quite cryptic. But they are all occurring for the because RootState['settings'] doesn't have an all property.

TS2355: A function whose declared type is neither undefined, 
        void, nor any must return a value.

Looking at the return value of RootState[K]['all'] it can feel confusing because we expect the all method to return a value. However, RootState['settings'] doesn't have an all property. If we call state.settings.all it evaluates to undefined.

TS2536: Type 'all' cannot be used to index type | RootState[K]

For the same reason, RootState[K]['all'] is an invalid type because the property doesn't exist on all properties of RootState. If cart, products and settings all had a property called all then this wouldn't be a problem.

TS2339: Property all does not exist on type 
| RootState['products'] 
| RootState['cart']  
| RootState['settings']

And finally, state[collection].all has this error because... wait for it... the all property doesn't exist on all properties of RootState.

Aside from these glaring issues, it won't complain if you call selectAllItems('settings') because keyof RootState is the valid type.

This is a problem because it's really the only TypeScript error we really want to see. We shouldn't be allowed to call selectAllItems('settings')because settings doesn't have an all property.

This is where this utility comes in handy:

function selectAllItems<
  Collection extends KeysHaveProperty<RootState, 'all'>
>(collection: Collection) {
  return (state: RootState): RootState[Collection]['all'] => {
    state[collection].all
  };
}

Now we are warned when we pass an invalid key name, and the correct return type is inferred:

useAppSelector(selectAllItems('settings')); // TS error
useAppSelector(selectAllItems('cart'));     // CartItem[]
useAppSelector(selectAllItems('products')); // Product[]

Breaking it down

This utility is a mapped type that returns all keys of the type that have a property with a certain name.

export type KeysHaveProperty<T, Prop extends string> = {
  [K in keyof T]: Prop extends keyof T[K] ? K : never;
}[keyof T];

We accept type (T) and property (Prop) generics.
We iterate over the keys (K) of T ([K in keyof T]).
We check if T[K] has Prop.
We return K if T[K]has`Prop.
We return never if T[K] doesn't have Prop.
Finally we declare the resulting type [keyof T] to get a union of all the keys that have the Prop.

Hopefully you find this useful :)

Run a command until it succeeds

teamradhq — Fri, 14 Oct 2022 07:30:54 +0000

A simple BASH pattern that came in handy recently:

Run command every time it fails until it doesn't fail.

command  
while [ $? -ne 0 ]; do  
    command  
done

Example

There was a long-running job that required export hundreds of thousands of records in small batches.

When it was initially written, it was possible to set a page offset so that it could be resumed upon failure.

vendor-export --batch-size=250 --offset=20

I performed a dry run with production data over the course of a week. This allowed me to implement error handling for every possible data error that might occur. And I was confident that the job would run in its entirety without failing due to any circumstance within our control.

But there was nothing practical we could do to mitigate network errors. It's definitely possible to implement a retry loop for these cases, but it wasn't practical within this system as it would affect other critical systems. Given that the process is single use, the risk presented in the work couldn't be justified.

And this is where the pattern comes in...

By adding a resume option to the long-running command it was possible to pick up exactly where the job failed:

vendor-export --batch-size=250 --resume

Now, when it's time to actually run the job, just call this:

vendor-export --batch-size=250 --resume

while [ $? -ne 0 ]; do  
    vendor-export --batch-size=250 --resume
done

Then go outside and enjoy the day...

Oops... There's may be a tiny problem with this...

If you've already tried this pattern out, you may have found this already:

In some terminals, ctrl-c won't interrupt the process.

It's not always the case. But sometimes this can happen.

If you encounter the problem, you just need to trap ctrl-c and exit:

function quit-it() {
    exit 0  
}  

vendor-export --batch-size=250 --resume

while [ $? -ne 0 ]; do  
    trap quit-it INT  
    vendor-export --batch-size=250 --resume
done

Pro Tip: Learn to love bugs through understanding

teamradhq — Wed, 28 Sep 2022 08:17:26 +0000

After squashing some bugs today, I remarked to a colleague how much I enjoy solving bugs. They were a bit puzzled at why somebody would enjoy that special kind of trauma, which stimulated a few philosophical thoughts about bugs and idiots...

1. There is no such thing as a computer bug

100% of bugs originate between the computer and the chair.

This is a really important concept to understand: Computer bugs don't exist. There is literally no such thing as a computer error.

A bug is not a computer error, it's a human error.
A computer cannot make an error, it does exactly what it's told to do.
If a computer's computations yield unexpected results, it's because some human made a mistake.

It's important to not only understand this, but also believe it wholeheartedly. It's impossible for a computer to make an error. It just does what some human told it.

2. This is because computers are stupid

By computer standards you are Skynet.

Computers have a real way with making you feel stupid when they don't do what you want. You have to remember, you're not the stupid one in the equation. Compared to a computer, you possess super-intelligence. Even if you're not that smart, by human standards.

If you can't understand what the computer's telling you, it's because:

The computer is incapable of telling you anything.
Some error cause at a lower level is not being handled appropriately.
This means there's nothing - beyond a stack trace - to give you meaningful context.

Always remember this. The computer's not doing what you tell it to because you're stupid. It's doing exactly what you told it to, because it's too stupid to understand the nuances of your statements. Realise that it's doing exactly what you told it to, you just need to take more time to dumb it down even further so that your code describes your vague intentions with precision.

3. Humans can also be idiots

There are many kinds of idiots in this world:

Clever idiots
Stupid idiots
Lazy idiots
Productive idiots
Idiots from the past
Idiots from the future

To name a few...

There's nothing wrong with idiotic behaviour. It's really really hard to articulate vague concepts with precision. In fact, stupidity is often a requirement to getting anything done at all, because of point 2. Computers are stupid, so we frequently have to find the dumbest way to say something that it can actually understand.

Try not to be an idiot as much as possible. And whenever you encounter idiots in your travels, be kind, because...

4. Quite often, you are the idiot

There comes a point in every engineer's life when they're reviewing some defect in a system and they mutter this mantra to themselves for the first time:

What idiot done this?

Typically, they'll be scratching their head, shaking it in disbelief or stupidly smiling at the screen. Over time it's exceedingly common that, when one composes oneself, they discover that they were the idiot that done this.

You have to accept that this is part of the life that you've chosen to live.

Past you is not an idiot.

They just don't have the knowledge you possess to know their choices are idiotic.
They had no practise doing the kind of implementation that you've done countless times.
They were smart enough to feel clever but too stupid to know that they're not.

Be kind, and when you're not the idiot from the past, be kinder still.

5. Be kind, take your time

This is super important!!!

No matter how critical an issue is, take as much time as you need, and be kind and understanding to any stakeholders you're engaged with.

Just remember:

Whatever issue is occurring is extremely disruptive to them.
This triggers a sense of urgency that can often lead to an emotional response.
Disregard negativity for now and validate their concerns.
Reflect on behaviour later determine whether you need to address this with them.
Focus on the task at hand.

Again, this is really important.

You need time and patience to defeat the unknown. If you maintain good relationships with your stakeholders, the space you need is easy to find. Even if you're not a very social or communicative person, if you understand how to display empathy and sympathy to the people you work with, you'll be fine here.

6. Being authentic

For me, this means being positive, about everything. If you have no idea if a thing is going to work, communicate this. If you're worried or stressed about the thing, say so.

Being authentic is the difference between saying:

It can't be done.

And:

I don't know how it can be done yet.

The first statement is absolute and final. It's maybe even a little negative and defeatist, showing some insecurity in the speaker. The second is open and authentic. It's optimistic and hopeful. Both of them mean exactly the same thing, it's just that the first one obfuscates the speaker's lack of knowledge.

By admitting the speaker has no knowledge, they're displaying confidence in their abilities to solve problems. After all, your job is to implement solutions to problems. If the solutions were already known, then you wouldn't have a job!

7. When in doubt, hit it with a hammer

I cannot stress this enough, if it's already broken, then break it some more!

I don't mean this in the lame "Move fast and break things" kind of way. See points on idiocy if you want to know what I think about that philosophy.

I mean to say that, most of time, you're encountering some kind of problem that somebody's solved before. Even if it's unique, the problem will fall into some domain that somebody's previously encountered.

There will be tools... Lots of tools... Use all of them like a hammer.

Use git bisect to isolate where the problem was introduced.
Output a bunch of debug log messages.
Set breakpoints.
Die and dump.
Write tests.

If you keep bashing your code over the head with a hammer, eventually it will talk and tell you everything you needed to know.

Conclusion

These are just some random points that came to mind today about bugs and human errors. Remember, you're a sophisticated human dealing with idiotic machines.

Clean Code Chapter 2

teamradhq — Wed, 21 Sep 2022 07:18:34 +0000

I'm currently reading Clean Code by Robert C Martin. Here are some of my takeaways, chapter by chapter.

Writing meaningful names.

This chapter is all about naming things. I can identify with the challenges and complexities of naming things, and also the hesitance to rename something when we feel its name isn't meaningful or accurate.

Probably my biggest takeaway from this chapter was:

The length of a name should correspond to the size of its scope.

- Page 22

In essence, this chapter says:

Be accurate and explicit.
Use tools that make it easy to change names.
Longer, more descriptive names are usually better, unless
They contain redundant information.
Solution or Problem domain names are appropriate given the consumers of our code and its concepts.

Use intention revealing names

The name of a function, variable or class should answer all of the big questions:
- Why does it exist?
- What does it do?
- How is it used?

function calculateCartItemTotal(item: CartItem): number

function calculateCartTotal(items: CartItem[]): number

Avoid disinformation

Don't use words with specific meanings to mean something else.
Beware of using names which vary in small ways.
Using inconsistent / incorrect spelling is disinformation.

Make meaningful distinctions

If names must be different, then they should also mean something different.
Number series aren't dis-informative, they're non-informative: a1, a2, a3 ... aN
Don't use noise words: ProductInfo and ProductData, they mean the same thing.
Type information does NOT belong in variable names.

/* Don't encode type info in variable names */
const nameString = 'name';
const totalFloat = 85.99;
const quantityInteger = 2;

/* Don't use similar names for different things. */
function parseIn(a, b)
function parseOut(a, b)

/* Use explicit names that clearly indicate purpose, intention and usage. */
function parseInputItemsToJson(inputItems, itemsJson)
function parseOutputItemsJson(itemsJson, outputContent)

Use searchable names

It's much easier to find MAX_USERS_ALLOWED than it is to find the number 7
The letter e is a terrible name for a variable because it's the most common letter in the english language:
- event
- exception
- error
- energy
- element
Single letter variables can only be used locally inside very small methods.

Avoid Encodings

There's enough encodings to deal with already.
IDEs are able to extract information about a reference's type without encoding it in its name.
They're also great at auto completion, so it's better to use a longer name using clear, plain language.
Examples of encodings to avoid:
- Type encodings: propertyString
- Member prefix: m_property
- Interface: SomeModuleInterface
- Factory: ISomeModuleFactory

Other Highlights

Avoid cultural references
Don't use slang or colloquialisms.
Don't make names clever.
Say what you mean, mean what you say.
Pick one word per concept and don't use puns.
Use solution domain names because other engineers will be able to infer their meaning.
Use problem domain names as non-technical stakeholders will be able to infer their meaning.

Clean Code Chapter 1

teamradhq — Mon, 19 Sep 2022 09:21:30 +0000

I'm currently reading Clean Code by Robert C Martin. Here are some of my takeaways, chapter by chapter.

There will be code

Essentially, no matter how sophisticated software applications become, there is a layer of abstraction that cannot be achieved without human intervention.

The folks who think that code will one day disappear are like mathematicians who hope one day to discover a mathematics that does not have to be formal. They are hoping that one day we will discover a way to create machines that can do what we want rather than what we say. These machines will have to be able to understand us so well that they can translate vaguely specified needs into perfectly executing programs that precisely meet those needs.

Page 2

Bad Code

Bad code has the potential to bring a project down.
We wade through bad code: it impedes our progress, and changing it is a struggle.
Bad code rots faster than clean code.

The total cost of owning a mess

As mess increases, team productivity decreases.
Redesigning doesn't solve the problem, it just adds to it.
- The new system has to replicate the old system, keeping up with any changes.
- By the time the system is near to complete, it's potentially so messy that it needs a redesign as well.
The mess of bad code is your fault.
- Non-technical stakeholders look to you for the information required to make promises and commitments.
- Even when we're not asked, we should forthright with our opinions.
- It's unprofessional to bend to the will of stakeholders who don't understand the risk of making messes.

Schools of thought

No school of thought is correct.
Different schools evolve from disagreements with existing forms.
One doesn't have to accept the truth of different schools of thought.
One should see, and respect, the other's point of view.

We are authors

We are writers of literature.
The main purpose of our code is to be read.
The majority of our time spent on a program is consumed by reading.

The boy scout rule

Leave the campground cleaner than you found it.
Don't submit new code without first cleaning up the existing code.
Ensure that every submission not only delivers the requested feature, but also improves the underlying system specification.

Bibliography

Implementation Patterns, Kent Beck, Addison Wesley, 2007.
Literate Programming, Donald E Knuth, Centre for the Study of Language and Information, Leland Stanford Junior University, 1992.

Stupid Code: Extract complex expressions

teamradhq — Wed, 14 Sep 2022 09:19:12 +0000

Clever code is for ninjas. Write stupid code for stupid computers (and people)...

Clever

Every expression should be placed inline because a clever person can clearly see what's going on here:

if (
    e.clientWidth < MAX_WIDTH 
    && e.clientHeight < MAX_HEIGHT
    && isVisible({ e, isFullyVisible: true})
) { 
    // OMG so many clever :-O
}

Let's face it, if a person is too stupid to understand what this means then they have no business understanding it in the first place. Right?

Even Cleverererer

It's even better when you put everything on one line and provide a multi-line comment that shows how clever you are:

/** 
 * If the element is fully visible and its 
 * dimension are within the allowed range, 
 * then we should do something. 
 */
if (e.clientWidth < MAX_WIDTH && e.clientHeight < MAX_HEIGHT && isVisible({ e, isFullyVisible: true})) { 
   // Stupidly clever :-S
}

This way, less clever people can marvel at your logic, even though they're incapable of reasoning about it.

Average

Extracting a complex expression is only required if you have to work with average people:

const isElementInRangeAndFullyVisible = (
    element.clientWidth < MAX_WIDTH
    && element.clientHeight < MAX_HEIGHT
    && isVisible({ element, isFullyVisible: true})
);

if (isElementInRangeAndFullyVisible) {
    // Now I can has understand B-)
}

But who has time for average? Obviously, we should only accept the very best code. And this code should be a reflection this to attract only the most clever people to work on it. If an average engineer can understand your code, you're doing it wrong fool!

Stupid

Only a stupid person would need a plain text description and a stupidly specific name to understand what's happening.

/**
 * The `element` is within the max width and height and is
 * currently visible in the viewport.
 * 
 * @param element
 */
function isElementInRangeAndFullyVisible(element: HTMLElement) {
  const isWidthInRange = element.clientWidth < MAX_WIDTH;
  const isHeightInRange = element.clientHeight < MAX_HEIGHT;

  return isWidthInRange && isHeightInRange && isVisible({
    element,
    isFullyVisible: true,
  });
}

if (isElementInRangeAndFullyVisible(element)) {
    // I am five ;-P
}

I mean, who needs tool tips am I right?

That's all unless you want to read some rambling...

Explaining Stupid

A marginally less sarcastic explanation for the above rationale.

Rename abstact `e` letter variable to descriptive `element`.

If we're working within the DOM, then it seems pretty clear that this is an HTML element.
Assume that most JavaScript developers assume that e represents and event.
If we're working with a specific type of element, we could be more explicit. Guess what these variables represent?
- textarea
- script
- a
- li

Stupid is better here because we just need to read the variable name to understand what the condition is.

If this code were part of a class / object, then it would even be better to extract each of these to accessors.

interface SomeElement {
  isHeightInRange: boolean;
  isWidthInRange: boolean;
  isInRange: boolean;
  isFullyVisible: boolean;
  isInRangeAndFullyVisible: boolean;
}

Extract complex condition to explicitly named `isElementInRangeAndFullyVisible` variable.

Within the application context, it's stupidly clear what this is doing.
If we were ever to rename this variable, it should only be to make it longer, for example:
- wasElementInRangeAndFullyVisible
- isElementInRangeAndFullyVisibleRightNow
- isElementInRangeAndFullyVisibleAfterUpdatingProfile

Stupid is better here because you don't even need to worry about the content of that condition expresion. You can see that if the element is within range and is fully visible, then something is going to happen.

The only time we should worry about the condition is when that something doesn't happen, then we look at the condition and can see why.

In this case it's most likely one of two things:

The condition is wrong so we need to update its contents to accurately reflect its name.
The condition doesn't do what we think it does so we need to update its name to something more accurate.

Encapsulate complex condition to explicitly named function.

Let's face it, someone stupider than you will probably need to do this exact same thing in the future.
If you're lucky, a less stupid person might even be able to write some tests that prove your assumptions.

Stupid is better here because you have just made the implementation of your condition reusable:

if (isInRangeAndFullyVisible(header) {
  // ...
}

const visibleElements = [...elements].filter(isInRangeAndFullyVisible);

const result = isInRangeAndFullyVisible(header) ? doSomething(element) : doNothing(element);

And your stupidity has the added benefit of being testable:

it('should fail check if not in range and fully visible', () => {
  const element = document.querySelector('.not-visible');

  expect(isInRangeAndFullyVisible(element))
    .toBe(false);
});

it('should fail check if in range and partially visible', () => {
  const element = document.querySelector('.in-range.partially-visible');

  expect(isInRangeAndFullyVisible(element))
    .toBe(false);
});


it('should pass check if in range and partially visible', () => {
  const element = document.querySelector('.in-range.fully-visible');

  expect(isInRangeAndFullyVisible(element))
    .toBe(true);
});

Pro Tip: Report Issues

teamradhq — Wed, 14 Sep 2022 07:08:46 +0000

When I’m working in teams, a frequent compliment I get from project managers is something like the following:

It's so great that you open issues on Jira when you find work that needs to be done.

I really appreciate it, but I also consider that it’s my job as a senior developer to report issues.

And by report, I don’t mean:

Shooting a DM to the product owner
Mentioning it in standup
Telling a colleague

These are things you do after you’ve reported the issue.

Reporting an issue means opening your project management tool and submitting a new ticket.

Note

If you fall into the camp that thinks that engineers shouldn't be responsible for writing tickets, either stop that or stop reading this article! You'll get nothing out of this.

For the rest of you, don't think that I'm saying you should be a ticket writing machine. It's just that some cases, engineers are the best people to report an issue.

What to include in an issue report

When reporting an issue, you should at least aspire to provide some, if not all of the following information. For now, just assume we're submitting a bug report.

Summary

A one liner summarising the problem.

Investigation

Comprehensive details of investigation conducted and any information it generated.

Solution

A precise solution, if applicable, a range of possible solutions, or advice / suspicions.

Estimation

If applicable, provide a formal estimate with the given process.

An example report

This might be a good example of a bug report.

Summary

Nav menu should collapse when it loses focus

Investigation

While working on ACME-123 I found that the when the navigation menu is not working as expected.

Expected: When I move my mouse out of the menu, it should lose focus and collapse.
Actual: When I move my mouse out of the menu it stays open, and only closes if I make a selection from the menu.

Logs

Looking in the browser console, I can see the following error:TypeError: undefined is not a function //...

Solution

I'm not sure what's causing the issue. But I see the above error every time I move my mouse out of the menu area, so I suspect resolving this error fixes the problem.

Tell all your friends

After you've submitted your bug report, now it's time to do one of the following:

Shoot a DM to the product owner
Mention it in standup
Tell a colleague

Oh, and make sure to include a link to the ticket.

To report or not to report

Just because you can, it doesn't mean you should.

Some examples of issues you should consider reporting:

It's not directly related to your current work
If it's related to your current tasks, just fix it.
Otherwise, add a report so that it can be actioned later.
It affects production systems reliability
In this case, you should outline what its effect is so that it can be assessed and prioritised accordingly.
It will change the current system operations
In this case, outline what the change would be and why it needs to be made.

Some examples of issues you might consider not reporting:

It won’t have any perceivable change to the system
It's very difficult to make a case for something that won't make any difference to the existing business operations.
It’s only relevant to developers
Work that only effects developers almost always sinks to the bottom of the pile. If you want this work to progress, you need to be sneaky.
Reporting it would take longer than fixing it
In this case, it's quicker to include the change with an existing task and make a note of it for testers to check.

DEV Community: teamradhq

Utility Type: PrependArgs

Example: Handling Electron IPC Events

Breaking it down.

Utility Type: WithPrefix

Example: API routes

Breaking it down

Reference

Utility Type: KeyHasProperties

Example: Dynamic Redux Selectors

Breaking it down

Run a command until it succeeds

Oops... There's may be a tiny problem with this...

Pro Tip: Learn to love bugs through understanding

1. There is no such thing as a computer bug

2. This is because computers are stupid

3. Humans can also be idiots

4. Quite often, you are the idiot

5. Be kind, take your time

6. Being authentic

7. When in doubt, hit it with a hammer

Conclusion

Clean Code Chapter 2

Writing meaningful names.

Use intention revealing names

Avoid disinformation

Make meaningful distinctions

Use searchable names

Avoid Encodings

Other Highlights

Clean Code Chapter 1

There will be code

Bad Code

The total cost of owning a mess

Schools of thought

We are authors

The boy scout rule

Bibliography

Stupid Code: Extract complex expressions

Clever

Even Cleverererer

Average

Stupid

Explaining Stupid

Rename abstact e letter variable to descriptive element.

Extract complex condition to explicitly named isElementInRangeAndFullyVisible variable.

Encapsulate complex condition to explicitly named function.

Pro Tip: Report Issues

What to include in an issue report

Summary

Related Items

Investigation

Solution

Estimation

An example report

Summary

Related Items

Investigation

Logs

Solution

Tell all your friends

To report or not to report

Rename abstact `e` letter variable to descriptive `element`.

Extract complex condition to explicitly named `isElementInRangeAndFullyVisible` variable.