feat: typescript-guidelines

[karlos1337]

Reason for change

Adds typescript guidelines.

List of Changes

• Typescript guidelines

Checklist

• I have updated necessary documentation and links in the README.md or the doc folder
• I have rebased from master, written good commit messages and squashed unnecessary commits

[artero]

What do you think about splitting the examples into at least two subsections to better illustrate each concept?

[karlos1337]

I've reordered the examples and added some explanation to each line. I don't fully understand what you mean; in that section, it doesn't make sense to split the examples since they follow the same code flow.

[xredo]

Very complete @karlos1337. Thank you for starting this! 😄 I still need to read carefully some of the sections and think about some of the points. Will do in the following weeks.

For now there are 3 basic things that we should cover from the start:

1. State that we prefer types instead of interfaces.
2. Our philosophy regarding implicit / explicit return types.
3. Named types vs anonymous types

I remember we used to have different opinions on the second statement. What's your opinion now? Perhaps we could discuss it.

Regarding the third statement, this is particularly relevant in React, where we use props as input parameters. I would like us to be consistent across projects. I don't have a strong opinion, but I tend to prefer anonymous types when they don't need to be reused, as it can sometimes be challenging to come up with the best names for those types, or they may add unnecessary boilerplate.

[karlos1337]

1. State that we prefer types instead of interfaces.

I don't have a strong opinion, but I'd say types are more usable and readable than interfaces. It's not a huge difference anyway; you could achieve the same with both.

2. Our philosophy regarding implicit / explicit return types.

My problem with this is not really about implicit vs. explicit; it's more about returning implicit and not being conscious about what you are returning. Most of the time, that implies returning a very complex type inferred from your logic, which, later on, could be a problem to handle or maintain. Using explicit, you are fully conscious of what you are returning, resulting in better code flow.

3. Named types vs anonymous types

I prefer named types and always export them. Other cases imply hiding those types and, in case you need them (because it's better to derive than repeat), forcing you to unwrap (nightmare) or invent a folder structure to move every shared type there with weird organization (or no organization at all).

Regarding the third statement, this is particularly relevant in React, where we use props as input parameters. I would like us to be consistent across projects. I don't have a strong opinion, but I tend to prefer anonymous types when they don't need to be reused, as it can sometimes be challenging to come up with the best names for those types, or they may add unnecessary boilerplate.

IMO that's never unnecessary. Creating types from bottom to top will make component props types straightforward, and 99% of the time, I think that names will be obvious

export type MyComponentProps =  { 
  user?: User,
  productsCount?: number
 };

export const MyComponent ({ user = {}, productsCount = 0 }: MyComponentProps) => {
...
}