diff --git a/.vitepress/theme/components/CustomLayout.vue b/.vitepress/theme/components/CustomLayout.vue new file mode 100644 index 00000000..22982b86 --- /dev/null +++ b/.vitepress/theme/components/CustomLayout.vue @@ -0,0 +1,67 @@ + + + + + diff --git a/.vitepress/theme/index.mjs b/.vitepress/theme/index.mjs index bfeef05c..3752bdad 100644 --- a/.vitepress/theme/index.mjs +++ b/.vitepress/theme/index.mjs @@ -3,12 +3,14 @@ import "./style.css"; import PageInfo from "./components/PageInfo.vue"; import PageTitle from "./components/PageTitle.vue"; import FutureStar from "./components/FutureStar.vue"; +import CustomLayout from "./components/CustomLayout.vue"; /** * @typedef {import('vitepress').EnhanceAppContext} EnhanceAppContext */ export default { - ...DefaultTheme, + extends: DefaultTheme, + Layout: CustomLayout, /** * @param {EnhanceAppContext} ctx context * @returns {void} diff --git "a/documents/forJava/Java\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204.md" "b/documents/forJava/Java\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204.md" index 5d4e6bd7..ec0c43cd 100644 --- "a/documents/forJava/Java\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204.md" +++ "b/documents/forJava/Java\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204.md" @@ -478,7 +478,6 @@ head: ソースのファイルヘッダにコピーライト標記は法的拘束力がないため、不要とする。 ただし、顧客からの要求があった場合を除く。 - Javadoc コメントには、少なくとも author と version(クラス)、param と return と exception(メソッド)を記述する - - 今後もバージョンアップのリリースが予定されているソースでは、上記に加えて since(バージョン)を記述する - `@Override`のあるメソッドでは、上記に加えて`{@Inherit}`を記述する @@ -667,7 +666,6 @@ head: return mi * 1609.344; } ``` - - リテラル定数の名前はその値の意味を正しく表現したものにする 悪い例: @@ -709,7 +707,6 @@ head: - 定数( `static` フィールド)に、 `static` ではないメソッドから書き込まない - 定数は、プリミティブ型もしくは、不変(Immutable)オブジェクトで参照する - - 不変`List`の生成には`List.of()`を利用する 良い例: @@ -913,7 +910,6 @@ head: ## メンバー順序 - 以下の順で記述する - 1. static フィールド 2. static イニシャライザー 3. static メソッド @@ -923,7 +919,6 @@ head: 7. メソッド - 同一カテゴリー内では以下の可視性の順で記述する - 1. public 2. protected 3. パッケージ private @@ -1560,7 +1555,6 @@ head: Java8 で追加されたメソッド。 拡張 for 文を利用したほうが多くの場合でデバッグに有利であり、可読性においても`forEach`の優位性は少ないため、`forEach`は原則利用しない。拡張 for 文を利用する。 具体的には下記のメソッドを利用しないこと。 - - `Collection#forEach` - `Set#forEach` - `List#forEach` @@ -1603,7 +1597,6 @@ head: - `Arrays.asList()`は利用せず、`List.of()`を利用する Java9 で追加されたメソッド。 配列を`List`に置き換える場合や、単純な固定の`List`を生成する際には`List.of()`を利用する。 - - `Arrays.asList()`と`List.of()`の違い `List.of()`で生成した`List`は、完全に不変(Immutable)な`List`で、 `Arrays.asList()`で生成した`List`は、サイズのみ不変で、`set`等による値の操作が可能な`List`です。 @@ -1849,13 +1842,11 @@ head: - 明確な方針で、利用する・利用しないを統一すること 方針無く、`var`を混在させるとソースコードの見通しと保守性が悪くなります。 各プロジェクトで、例えば以下ののような方針で統一してください。 - 1. `var`を利用しない 2. 原則`var`を利用する 3. 右辺で、明確に型がわかる場合は`var`を利用する 以下で`2`、`3`について例を示します。 - - 原則`var`を利用する 利用できる箇所は全て`var`を利用します。 @@ -1962,12 +1953,10 @@ head: ``` 次にポイントを説明します。 - - `{`の後、`}`の前に改行する - レコードコンポーネント(パラメータ)のカンマの後に改行することを推奨する レコードコンポーネントが少なく、レコードコンポーネント名からでも意味が理解でき、改行がなくても可読性が低下しない場合は、改行を必要としません。 改行を推奨する理由は以下です。 - - アノテーションを付与したときでも比較的読みやすい(アノテーション引数との混在による可読性の低下の回避) - レコードコンポーネントが多い場合も比較的読みやすい @@ -2355,7 +2344,6 @@ head: ``` なお、メソッドコメントには、適切な javadoc コメント(タグ)のほかに、以下の内容も可能な限り明記すること。 - - 副作用のある処理の場合は、その内容 (→ メソッドの引数オブジェクトがメソッド内で変更されるケースなど) - 既知のバグ (→ 判明しているが修正しないことにした場合など) - 影響のある事前条件、事後条件 (→ メソッドが正しく動作するための前提について) diff --git "a/documents/forJava/Java\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204_for_11.md" "b/documents/forJava/Java\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204_for_11.md" index 8cf3afd3..0dc94456 100644 --- "a/documents/forJava/Java\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204_for_11.md" +++ "b/documents/forJava/Java\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204_for_11.md" @@ -478,7 +478,6 @@ head: ソースのファイルヘッダにコピーライト標記は法的拘束力がないため、不要とする。 ただし、顧客からの要求があった場合を除く。 - Javadoc コメントには、少なくとも author と version(クラス)、param と return と exception(メソッド)を記述する - - 今後もバージョンアップのリリースが予定されているソースでは、上記に加えて since(バージョン)を記述する - `@Override`のあるメソッドでは、上記に加えて`{@Inherit}`を記述する @@ -667,7 +666,6 @@ head: return mi * 1609.344; } ``` - - リテラル定数の名前はその値の意味を正しく表現したものにする 悪い例: @@ -709,7 +707,6 @@ head: - 定数( `static` フィールド)に、 `static` ではないメソッドから書き込まない - 定数は、プリミティブ型もしくは、不変(Immutable)オブジェクトで参照する - - 不変`List`の生成には`List.of()`を利用する 良い例: @@ -913,7 +910,6 @@ head: ## メンバー順序 - 以下の順で記述する - 1. static フィールド 2. static イニシャライザー 3. static メソッド @@ -923,7 +919,6 @@ head: 7. メソッド - 同一カテゴリー内では以下の可視性の順で記述する - 1. public 2. protected 3. パッケージ private @@ -1324,7 +1319,6 @@ head: Java8 で追加されたメソッド。 拡張 for 文を利用したほうが多くの場合でデバッグに有利であり、可読性においても`forEach`の優位性は少ないため、`forEach`は原則利用しない。拡張 for 文を利用する。 具体的には下記のメソッドを利用しないこと。 - - `Collection#forEach` - `Set#forEach` - `List#forEach` @@ -1367,7 +1361,6 @@ head: - `Arrays.asList()`は利用せず、`List.of()`を利用する Java9 で追加されたメソッド。 配列を`List`に置き換える場合や、単純な固定の`List`を生成する際には`List.of()`を利用する。 - - `Arrays.asList()`と`List.of()`の違い `List.of()`で生成した`List`は、完全に不変(Immutable)な`List`で、 `Arrays.asList()`で生成した`List`は、サイズのみ不変で、`set`等による値の操作が可能な`List`です。 @@ -1613,13 +1606,11 @@ head: - 明確な方針で、利用する・利用しないを統一すること 方針無く、`var`を混在させるとソースコードの見通しと保守性が悪くなります。 各プロジェクトで、例えば以下ののような方針で統一してください。 - 1. `var`を利用しない 2. 原則`var`を利用する 3. 右辺で、明確に型がわかる場合は`var`を利用する 以下で`2`、`3`について例を示します。 - - 原則`var`を利用する 利用できる箇所は全て`var`を利用します。 @@ -1768,7 +1759,6 @@ head: ``` なお、メソッドコメントには、適切な javadoc コメント(タグ)のほかに、以下の内容も可能な限り明記すること。 - - 副作用のある処理の場合は、その内容 (→ メソッドの引数オブジェクトがメソッド内で変更されるケースなど) - 既知のバグ (→ 判明しているが修正しないことにした場合など) - 影響のある事前条件、事後条件 (→ メソッドが正しく動作するための前提について) diff --git "a/documents/forJava/Java\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204_for_8.md" "b/documents/forJava/Java\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204_for_8.md" index 421e5ce2..88f302f8 100644 --- "a/documents/forJava/Java\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204_for_8.md" +++ "b/documents/forJava/Java\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204_for_8.md" @@ -478,7 +478,6 @@ head: ソースのファイルヘッダにコピーライト標記は法的拘束力がないため、不要とする。 ただし、顧客からの要求があった場合を除く。 - Javadoc コメントには、少なくとも author と version(クラス)、param と return と exception(メソッド)を記述する - - 今後もバージョンアップのリリースが予定されているソースでは、上記に加えて since(バージョン)を記述する - `@Override`のあるメソッドでは、上記に加えて`{@Inherit}`を記述する @@ -667,7 +666,6 @@ head: return mi * 1609.344; } ``` - - リテラル定数の名前はその値の意味を正しく表現したものにする 悪い例: @@ -709,7 +707,6 @@ head: - 定数( `static` フィールド)に、 `static` ではないメソッドから書き込まない - 定数は、プリミティブ型もしくは、不変(Immutable)オブジェクトで参照する - - 不変`List`の生成には`Collections`クラスの`unmodifiableList()`メソッドを利用する 良い例: @@ -919,7 +916,6 @@ head: ## メンバー順序 - 以下の順で記述する - 1. static フィールド 2. static イニシャライザー 3. static メソッド @@ -929,7 +925,6 @@ head: 7. メソッド - 同一カテゴリー内では以下の可視性の順で記述する - 1. public 2. protected 3. パッケージ private @@ -1312,7 +1307,6 @@ head: Java8 で追加されたメソッド。 拡張 for 文を利用したほうが多くの場合でデバッグに有利であり、可読性においても`forEach`の優位性は少ないため、`forEach`は原則利用しない。拡張 for 文を利用する。 具体的には下記のメソッドを利用しないこと。 - - `Collection#forEach` - `Set#forEach` - `List#forEach` @@ -1674,7 +1668,6 @@ head: ``` なお、メソッドコメントには、適切な javadoc コメント(タグ)のほかに、以下の内容も可能な限り明記すること。 - - 副作用のある処理の場合は、その内容 (→ メソッドの引数オブジェクトがメソッド内で変更されるケースなど) - 既知のバグ (→ 判明しているが修正しないことにした場合など) - 影響のある事前条件、事後条件 (→ メソッドが正しく動作するための前提について) diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md b/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md index 01a594e0..fc1700ff 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_2.0.md @@ -108,7 +108,6 @@ description: "何かしらの説明" - account_type - register_at ``` - - YAML は項目定義がネストすることで縦長な定義になりやすい。情報密度を上げるために配列リテラルを推奨する ## 改行の表現 @@ -499,7 +498,6 @@ URL に紐づく HTTP メソッドで、1 つの操作を定義します。 - `pattern`, `minLength`, `maxLength` などの条件について - [https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#fixed-fields-7](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#fixed-fields-7) を参考に、指定できる条件はなるべく細かく指定する - `schema` - - リクエストボディは、`$ref` を用いて、`#/definitions` 配下に記載する。**$ref を用いない記載は許可しない。** ```yaml @@ -524,7 +522,6 @@ URL に紐づく HTTP メソッドで、1 つの操作を定義します。 type: string ... ``` - - モデル名は、 `{HTTPメソッド名}{物理名}` の PascalCase で記載する - 例: PutUserAccount、PostUserAccount, PatchUserAccount @@ -638,7 +635,6 @@ URL に紐づく HTTP メソッドで、1 つの操作を定義します。 - モデル名は、PascalCase で記載する - 種別が配列の場合、ネストして定義するのではなく、 `$ref` を活用する - もし、リソース名が単複同形で `type: array` と区別できない場合、 `List` を末尾に付けて区別する - - そうではない場合は `s` を付けて表現する ```yml diff --git a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md index cdbd73ce..75cfd4f1 100644 --- a/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md +++ b/documents/forOpenAPISpecification/OpenAPI_Specification_3.0.3.md @@ -109,7 +109,6 @@ description: "何かしらの説明" - account_type - register_at ``` - - YAML は項目定義がネストすることで縦長な定義になりやすい。情報密度を上げるために配列リテラルを推奨する ## 改行の表現 @@ -203,7 +202,6 @@ Web API が提供する機能の概要・想定する利用者やユースケー アプリケーションのバージョン(git tag やリリースで管理するようなバージョン)とは別である。 - `major.minor` 形式を推奨する - - `0.1` 固定で開発を進め、サービスのリリース時に `1.0` とし、その後の項目やオプション、パスの追加ごとにマイナーバージョンをインクリメントしていく 良い例: @@ -428,7 +426,6 @@ paths: API を識別するための一意な文字列を記載する。 - HTTP メソッドと URL パスの組み合わせをキャメルケースで表現する - - キャメルケースの書式は、[OpenAPI 3.0ガイドのPaths and Operations](https://swagger.io/docs/specification/paths-and-operations/#:~:text=role%3Dvalue-,operationId,-operationId%20is%20an)でも利用されているため、一般的である 良い例: @@ -572,7 +569,6 @@ API のリクエストボディを記載する。 ``` - リクエストボディそのものは通常複数の API を跨いで再利用されるものではないため、原則 `components` オブジェクトとして共通化(コンポーネント化)を行わない - - [openapi-generator](https://github.com/OpenAPITools/openapi-generator)を使用する場合は、コンポーネント化をせず、`title` を指定することで名称の指定が可能となる - [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen)を使用する場合は、名称を指定するためにコンポーネント化が必要となるが、極力コンポーネント化せずデフォルトの名称を使用することを推奨する @@ -613,7 +609,6 @@ API のリクエストボディを記載する。 API のレスポンスを記載する。 - 正常系(`2xx`)のレスポンスは通常複数の API を跨いで再利用されるものではないため、原則 `components` オブジェクトとして共通化(コンポーネント化)を行わない - - [openapi-generator](https://github.com/OpenAPITools/openapi-generator)を使用する場合は、コンポーネント化をせず、`title` を指定することで名称の指定が可能となる - [oapi-codegen](https://github.com/oapi-codegen/oapi-codegen)を使用する場合は、レスポンスの構造体を出力するために `strict-server` オプションを `true` に指定する必要がある。名称を指定するためにコンポーネント化が必要となるが、極力コンポーネント化せずデフォルトの名称を使用することを推奨する diff --git "a/documents/forSQL/SQL\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204\357\274\210Oracle\357\274\211.md" "b/documents/forSQL/SQL\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204\357\274\210Oracle\357\274\211.md" index 5d132576..480f2e35 100644 --- "a/documents/forSQL/SQL\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204\357\274\210Oracle\357\274\211.md" +++ "b/documents/forSQL/SQL\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204\357\274\210Oracle\357\274\211.md" @@ -447,7 +447,6 @@ WHERE - 条件式の順序 原則として、WHERE 句で条件式を列挙する際、下記の順序を守ること。 - 1. テーブル単位にまとめて順番に記述する この際、テーブルの順序は FROM 句に記述した順序に準ずること。 2. 1.のテーブル単位の中で絞り込み条件をまず記述し、その後結合条件を記述する。 @@ -499,7 +498,6 @@ WHERE - 可能な限り検索条件にパーティションキーの値を指定する - 全列ワイルドカード「`*`」の使用はせず、カラム名を明記する - インデックスによる検索を指定したい場合、下記の記載を行わない - - インデックスカラムを含む演算に対して条件指定 悪い例: diff --git "a/documents/forSQL/SQL\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204\357\274\210PostgreSQL\357\274\211.md" "b/documents/forSQL/SQL\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204\357\274\210PostgreSQL\357\274\211.md" index 86f0772d..db551516 100644 --- "a/documents/forSQL/SQL\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204\357\274\210PostgreSQL\357\274\211.md" +++ "b/documents/forSQL/SQL\343\202\263\343\203\274\343\203\207\343\202\243\343\203\263\343\202\260\350\246\217\347\264\204\357\274\210PostgreSQL\357\274\211.md" @@ -414,7 +414,6 @@ where - 条件式の順序 原則として、WHERE 句で条件式を列挙する際、下記の順序を守ること。 - 1. テーブル単位にまとめて順番に記述する この際、テーブルの順序は FROM 句に記述した順序に準ずること。 2. 1.のテーブル単位の中で絞り込み条件をまず記述し、その後結合条件を記述する。 @@ -496,7 +495,6 @@ set - 可能な限り検索条件にパーティションキーの値を指定する - 全列ワイルドカード「`*`」の使用はせず、カラム名を明記する - インデックスによる検索を指定したい場合、下記の記載を行わない - - インデックスカラムを含む演算に対して条件指定 悪い例: