Skip to content

Commit 3c45015

Browse files
unionalunional
committed
add comments
1 parent 8531c5c commit 3c45015

17 files changed

+205
-23
lines changed

‎.editorconfig

+1-1
Original file line numberDiff line numberDiff line change
@@ -11,5 +11,5 @@ indent_size = 2
1111
indent_style = tab
1212
trim_trailing_whitespace = true
1313

14-
[*.{yml,yaml}]
14+
[*.{md,mdx,yml,yaml}]
1515
indent_style = space

‎.prettierignore

+2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
11
*.json
2+
*.md
3+
*.mdx
24
*.yml
35
*.yaml

‎.vscode/extensions.json

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,6 @@
88
"editorconfig.editorconfig",
99
"unifiedjs.vscode-mdx",
1010
"yzhang.markdown-all-in-one",
11-
"streetsidesoftware.code-spell-checker"
11+
"bradlc.vscode-tailwindcss"
1212
]
1313
}

‎github-page/blog/2023-04-13-equality-is-hard.mdx

+4
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
2+
3+
- not sound
4+
-

‎github-page/docs/guidelines/documentations/comments.md

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
---
2+
slug: comments
3+
title: "Creating rich comments"
4+
authors: [unional]
5+
tags: [comment, documentation, DX]
6+
---
7+
8+
# Comments
9+
10+
You **should** add JSDoc comments to your code.
11+
12+
> Why?
13+
14+
For a long time, I does not do this.
15+
My belief was that the code should be self-explanatory.
16+
17+
However, having the comments in the code,
18+
especially when it is a public API,
19+
makes it a lot easier for consumer to use the code.
20+
21+
Especially if you can provide examples in the comments.
22+
23+
For example, the following is a comment for the `Equal` type in [type-plus]:
24+
25+
```ts
26+
/**
27+
* Checks `A` and `B` are equal.
28+
*
29+
* ```ts
30+
* type R = Equal<1, 1> // true
31+
* type R = Equal<any, any> // true
32+
* type R = Equal<boolean, boolean> // true
33+
* type R = Equal<true, true> // true
34+
* type R = Equal<[1], [1]> // true
35+
*
36+
* type R = Equal<boolean, true> // false
37+
* type R = Equal<any, 1> // false
38+
* type R = Equal<[any], [1]> // false
39+
* type R = Equal<{ a: 1 }, { a: 1; b: 2 }> // false
40+
* ```
41+
*/
42+
export type Equal<A, B, Then = true, Else = false> = ...
43+
```
44+
45+
---
46+
47+
You **should not** include import statements in the comment examples.
48+
49+
> Why?
50+
51+
Your code or type can be reused in different context.
52+
The import statement might not be the same in different contexts.
53+
54+
For example, your code might be reused in another package.
55+
So the import statement will provide the wrong information.
56+
57+
❌ Bad
58+
59+
```ts
60+
/**
61+
* Check if the type `T` is exactly `any`.
62+
*
63+
* ```ts
64+
* import type { AnyType } from 'type-plus'
65+
*
66+
* type R = AnyType<any> // any
67+
*
68+
* type R = AnyType<never> // never
69+
* type R = AnyType<unknown> // never
70+
* type R = AnyType<string | boolean> // never
71+
* ```
72+
*/
73+
export type AnyType<T, Then = T, Else = never> = ...
74+
```
75+
76+
✅ Good
77+
78+
```ts
79+
/**
80+
* Check if the type `T` is exactly `any`.
81+
*
82+
* ```ts
83+
* type R = AnyType<any> // any
84+
*
85+
* type R = AnyType<never> // never
86+
* type R = AnyType<unknown> // never
87+
* type R = AnyType<string | boolean> // never
88+
* ```
89+
*/
90+
export type AnyType<T, Then = T, Else = never> = ...
91+
```
92+
93+
[type-plus]: https://github.com/unional/type-plus

‎github-page/docs/guidelines/files_and_folders/_category_.yml ‎github-page/docs/guidelines/files-and-folders/_category_.yml

File renamed without changes.

‎github-page/docs/guidelines/files_and_folders/naming_conventions.mdx ‎github-page/docs/guidelines/files-and-folders/naming-conventions.mdx

File renamed without changes.

‎github-page/docs/guidelines/project/npmignore.mdx

+19
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
---
2+
slug: npmignore
3+
title: ".npmignore file"
4+
authors: [unional]
5+
tags: [project]
6+
---
7+
8+
The `.npmignore` file is ued to keep stuff out of your package.
9+
10+
You **should not** use `.npmignore` file
11+
12+
> Why?
13+
14+
There are [problematic situations](https://medium.com/@jdxcode/for-the-love-of-god-dont-use-npmignore-f93c08909d8d) when using `.npmignore` file.
15+
16+
You can actually exclude files and folders using the [files field](./package-json#the-files-field).
17+
There is no reason to use `.npmignore` file.
18+
19+
- <https://docs.npmjs.com/cli/v9/using-npm/developers#keeping-files-out-of-your-package>

‎github-page/docs/guidelines/project/package-json.mdx

+55
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
slug: package-json
3+
title: "package.json"
4+
authors: [unional]
5+
tags: [project, typescript, tsconfig]
6+
---
7+
8+
## The `files` field
9+
10+
The `files` field is used to specify which files and folders to be included in the publish package.
11+
12+
You **should** always specify the `files` field.
13+
14+
> Why?
15+
16+
By default, files not excluded by `.gitignore` (or `.npmignore`) are included, which is not what you want.
17+
Also, files that are excluded by `.gitignore` are not included, which is likely also not what you want.
18+
19+
So it is always better to be explicit and control them yourself.
20+
21+
For example, if the `files` field is removed from [type-plus],
22+
23+
files like `.changeset/*`, `.github/*`, `.vscode/*` are included,
24+
while `cjs/*` and `esm/*` are not.
25+
26+
---
27+
28+
You **should** use `files` field to exclude test files.
29+
30+
For example, add this to your `files` field:
31+
32+
```json5
33+
{
34+
"files": [
35+
// your package files
36+
"cjs",
37+
"esm",
38+
"testing",
39+
"ts",
40+
// exclude test files
41+
"!**/*.{spec,test,unit,accept,integrate,system}.*"
42+
]
43+
}
44+
```
45+
46+
> Why?
47+
48+
Doing this allows you to keep your tsconfig setup simple.
49+
You will always compile all files, including your test files.
50+
51+
This ensures that your test files does not contain any syntax error.
52+
53+
- <https://docs.npmjs.com/cli/v9/configuring-npm/package-json#files>
54+
55+
[type-plus]: https://github.com/unional/type-plus

‎github-page/docs/tsconfig/isolated_modules.mdx

+6
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
2+
You **should** turn on `isolatedModules`.
3+
4+
> Why?
5+
6+
`SFT`

‎github-page/drafts/tips/type_cannot_be_named.md

+3
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Type
2+
3+
When using a package written in TypeScript,

‎page/src/components/GitHubBadge.tsx

+4-4
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ export function GitHubBadge() {
44
const result = useQuery({
55
queryKey: ['repo-stats'],
66
queryFn: async ({ signal }) => {
7-
const response = await fetch('https://api.github.com/repos/unional/typescript-guidelines', {
7+
const response = await fetch('https://api.github.com/repos/unional/typescript-blackbook', {
88
signal
99
})
1010
return response.json()
@@ -18,8 +18,8 @@ export function GitHubBadge() {
1818
<div className="rounded-l-sm outline outline-1 outline-gray-300 flex px-1 bg-gray-200">
1919
<a
2020
target="_blank"
21-
aria-label="Star TypeScript guidelines on GitHub"
22-
href="https://github.com/unional/typescript-guidelines"
21+
aria-label="Star TypeScript Blackbook on GitHub"
22+
href="https://github.com/unional/typescript-blackbook"
2323
className="flex items-center"
2424
>
2525
<img src="/svgs/github-mark.svg" className="h-4 w-4 mr-1" alt="github" />
@@ -30,7 +30,7 @@ export function GitHubBadge() {
3030
<a
3131
target="_blank"
3232
aria-label={`${result.data?.stargazers_count} stargazers on GitHub`}
33-
href="https://github.com/unional/typescript-guidelines/stargazers"
33+
href="https://github.com/unional/typescript-blackbook/stargazers"
3434
>
3535
{result.data?.stargazers_count}
3636
</a>

‎page/src/components/Header.tsx

+7-7
Original file line numberDiff line numberDiff line change
@@ -3,34 +3,34 @@ import { GitHubBadge } from './GitHubBadge'
33

44
const queryClient = new QueryClient()
55

6-
export function Header({ active }: { active?: 'blog' | 'guidelines' }) {
6+
export function Header({ active }: { active?: 'blog' | 'blackbook' }) {
77
return (
88
<QueryClientProvider client={queryClient}>
9-
<header className="bg-green-300">
9+
<header className="bg-violet-300">
1010
<nav className="flex gap-1 p-2 items-center">
1111
<div className="flex pr-4">
1212
<a aria-label="home" href="/" className="hover:outline rounded-sm py-1 px-2 outline-sky-700">
1313
<div className="flex font-chalk">
1414
<div className="pr-1">
1515
<img src="/svgs/ts-guidelines.svg" className="w-6" alt="icon" />
1616
</div>
17-
Guidelines
17+
Blackbook
1818
</div>
1919
</a>
2020
</div>
2121
<a
2222
className={`rounded-sm hover:bg-slate-300 py-1 px-2 ${active === 'blog' ? 'underline' : ''}`}
2323
href="/blogs"
2424
>
25-
Blog
25+
Blogs
2626
</a>
2727
<a
2828
className={`rounded-sm hover:bg-slate-300 py-1 px-2 ${
29-
active === 'guidelines' ? 'underline' : ''
29+
active === 'blackbook' ? 'underline' : ''
3030
}`}
31-
href="/guidelines"
31+
href="/blackbook"
3232
>
33-
Guidelines
33+
Blackbook
3434
</a>
3535
<div className="flex py-1 flex-grow justify-end">
3636
<GitHubBadge />

‎page/src/pages/blackbook.astro

+8
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
import { Header } from '../components/Header'
3+
import Layout from '../layouts/DocLayout.astro'
4+
---
5+
6+
<Layout title="TypeScript Blackbook">
7+
<Header slot="header" client:load active="blackbook" />
8+
</Layout>

‎page/src/pages/blogs.astro

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,6 @@ import { Header } from '../components/Header'
33
import Layout from '../layouts/DocLayout.astro'
44
---
55

6-
<Layout title="TypeScript Guidelines">
6+
<Layout title="TypeScript Blackbook">
77
<Header slot="header" client:load active="blog" />
88
</Layout>

‎page/src/pages/guidelines.astro

-8
This file was deleted.

‎page/src/pages/index.astro

+1-1
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,6 @@ import { Header } from '../components/Header'
33
import Layout from '../layouts/Layout.astro'
44
---
55

6-
<Layout title="TypeScript Guidelines">
6+
<Layout title="TypeScript Blackbook">
77
<Header client:load />
88
</Layout>

0 commit comments

Comments
 (0)