Refactoring Tip 2 of 6:

Prefer minimal code samples

As of writing, the following code appears on the official TypeScript handbook (which is written in a way that’s both a tutorial and documentation). And the handbook uses this code to explain how to use a particular TypeScript keyword/operator.

Question: Can you tell which keyword/operator is being explained through this code? Hint: It is one of the keywords/operators used in the code. (You don’t need to know TypeScript—just guess!)

function extend < First , Second > ( first : First , second : Second ) : First & Second { const result : Partial < First & Second > = { } for ( const prop in first ) { if ( first . hasOwnProperty ( prop ) ) { ; ( result as First ) [ prop ] = first [ prop ] } } for ( const prop in second ) { if ( second . hasOwnProperty ( prop ) ) { ; ( result as Second ) [ prop ] = second [ prop ] } } return result as First & Second } class Person { constructor ( public name : string ) { } } interface Loggable { log ( name : string ) : void } class ConsoleLogger implements Loggable { log ( name ) { console . log ( ` Hello, I'm ${ name } . ` ) } } const jim = extend ( new Person ( 'Jim' ) , ConsoleLogger . prototype ) jim . log ( jim . name )

Answer: The official TypeScript handbook uses the above code to explain how to use the “ & ” operator in TypeScript.

& ” operator creates an intersection of two types. You can learn more on (Brief explanation: In TypeScript, the “” operator creates an intersection of two types. You can learn more on my tutorial .)

But it’s hard to tell! If you look at the code again, only the highlighted part below is related to the “ & ” operator. There are too many other keywords that are just noise (e.g. Partial<> , hasOwnProperty , as , constructor , public , interface , void , implements , prototype , etc). You also need to pause and read carefully to understand what’s going on, even though most of the code isn’t directly related to the “ & ” operator.

Only the highlighted part is related to “ & ”, the topic being explained through this code. Every other keyword is just noise. function extend < First , Second > ( first : First , second : Second ) : First & Second { const result : Partial < First & Second > = { } for ( const prop in first ) { if ( first . hasOwnProperty ( prop ) ) { ; ( result as First ) [ prop ] = first [ prop ] } } for ( const prop in second ) { if ( second . hasOwnProperty ( prop ) ) { ; ( result as Second ) [ prop ] = second [ prop ] } } return result as First & Second } class Person { constructor ( public name : string ) { } } interface Loggable { log ( name : string ) : void } class ConsoleLogger implements Loggable { log ( name ) { console . log ( ` Hello, I'm ${ name } . ` ) } } const jim = extend ( new Person ( 'Jim' ) , ConsoleLogger . prototype ) jim . log ( jim . name )

So, in my opinion, the above code sample is NOT a great way to explain how to use the “ & ” operator in TypeScript. It does show a few places where the “ & ” operator can be used, which is good, but it could have been done without adding so much noise.

If I were to explain how the “ & ” operator works in TypeScript, I’d refactor the earlier code as follows—it basically does the same thing in a simpler way. You don’t need to understand TypeScript to know that this is more minimal and focused on explaining how to use the “ & ” operator. The amount it takes to understand this code is also much shorter.

If I were to explain how the “ & ” operator works, I’d rewrite the above code as follows—much simpler! type Person = { name : string } type Loggable = { log : ( name : string ) => void } const jim : Person & Loggable = { name : 'Jim' , log : name => { console . log ( ` Hello, I'm ${ name } . ` ) } } jim . log ( jim . name )

If you want to talk about more advanced usage, you could add the advanced example AFTER my simple example.

What I want to say is: Prefer minimal code samples, at least initially. If you’re trying to teach a new concept (let’s call this “X”), just focus on X in the code sample and don’t add too much extra stuff. Add extra stuff only (1) after you showed a simple example and (2) when it really helps the reader’s understanding.

Minimal reproducible example: When you ask a question on StackOverflow or file an issue on GitHub, you’re often asked to create a minimal reproducible example. Your code needs to be as small as possible, such that it is just sufficient to demonstrate the problem, but without any additional complexity (Wikipedia’s definition).

You should use the same principle when writing code samples for your tutorials. Ask yourself: Can I make this code sample more minimal while maintaining the learning experience?