diff --git a/doc/develop.jax b/doc/develop.jax index 5fade7b34..f9aa80f2a 100644 --- a/doc/develop.jax +++ b/doc/develop.jax @@ -1,4 +1,4 @@ -*develop.txt* For Vim バージョン 9.1. Last change: 2024 May 11 +*develop.txt* For Vim バージョン 9.1. Last change: 2024 Oct 31 VIMリファレンスマニュアル by Bram Moolenaar @@ -159,6 +159,7 @@ Vimは、そのユーザーに特定の作業パターンを強いるよりは よくしようとする装飾的なGUIエディタではない。しかし、機能的なGUI特性は歓迎さ れる。 + ============================================================================== 2. コーディングスタイル *coding-style* @@ -173,18 +174,20 @@ Vimのソースコードに変更を加える際、守るべきルールがあ コードに変更を加える基本的なステップは: 1. GitHub からコードを取得する。これによりあなたが変更したコードをメインのコー ドベースに同期するのがより簡単になる (あなたの変更がメインのコードベースに - 含まれるようになるまで少しかかるかもしれない) 。いくらか時間を費やして git - について学ぶ必要がある。git はあまりユーザーフレンドリーなツールではない。 + 含まれるようになるまで少しかかるかもしれない) 。 2. ドキュメントを調整する。最初にこれをやることで、あなたの行う変更がユーザー に与える影響について、おおまかな印象をもつことができる。 3. ソースコードに変更を加える。 4. 変更がリストされた項目に影響を与えていないか、../doc/todo.txtをチェックす る。 -5. "git diff" でパッチを作成する。GitHub でプルリクエストを作成しても良いが、 - 重要なのはその diff である。 -6. 何が変更されたかのノートを作成する。問題点とその解決策について書かれている - のが望ましい。|vim-dev| のメーリングリストに説明と diff を含めたメールを送 - るか GitHub でプルリクエストを作成する。 +5. 新しい動作を検証し、将来的に問題が発生しないことを確認するために、 + src/testdir にテストを追加する。 +6. "git diff" でパッチを作成する。 +7. 変更点について付記し、できれば問題と解決策についても記載すること。説明と差 + 分を添えて、|vim-dev| メーリングリストにメールを送信する。 + +些細な変更でない場合は、必ず github でプルリクエストを作成すること。これによ +り、テストスイートがトリガーされる。 ☆Cコンパイラ *style-compiler* *ANSI-C* *C89* *C99* @@ -194,54 +197,234 @@ Vimのソースコードに変更を加える際、守るべきルールがあ も 100% サポートされているわけではない。したがって、C99 機能の一部のみを使用 し、一部を明示的に禁止する (これは時間の経過とともに徐々に調整される)。 -現存するパッチに対してマージの問題を引き起こすため、C99の機能を使う変更を至る -所に入れてはいけない。新しくコードを書く場合、もしくは既存のコードを書き直す場 -合に限り使用してもよい。 +使用してはいけない機能 ~ + +これらの C99 の機能は、コンパイラのサポートが不十分なため使用してはいけない: +- 可変長配列 (C11 でもこれはオプショナルな機能である)。 +- C99 の _Bool 型と _Complex 型。 +- "inline" (ほとんど必要ない、コンパイラに最適化させよう。) +- フレキシブル配列メンバ: HP-UX C コンパイラはサポートしていない。(John + Marriott) -コメント ~ -慣習的に Vim では /* コメント */ を使用する。ファイルや関数のヘッダ、コードの -大きめなブロックに関してはこれを維持するつもりである。例: +☆コメント *style-comments* + +関数本体内に複数行のコメントを入れないようにすること。関数が非常に複雑で、一部 +を個別にコメントする必要がある場合は、関数の構造を再検討する必要がある。 + +ファイルヘッダーと関数の説明には以下を使用: > + /* + * Description + */ +< +その他すべてには以下を使用: > + // comment +< + + +☆インデント *style-indentation* + +コードのインデントには 4 つのスペースを使用する。Vim を使用してソースを編集し +ている場合は、|modeline| があるため何もする必要はない。 + +他のエディタの場合は、リポジトリのルートに `.editorconfig` が提供される。 + + +☆宣言 *style-declarations* + +可能であれば、ガード内で `for` ループ変数を宣言する: +OK: > + for (int i = 0; i < len; ++i) +< +間違い: > + int i; + for (i = 0; i < len; ++i) +< +常にデフォルト値を持つ変数を宣言する: +OK: > + int n = 0; + int *ptr = NULL; +< +間違い: > + int n; + int *ptr; +< + + +☆括弧 *style-braces* + +すべての波括弧は改行しなければならない: +OK: > + if (cond) + { + cmd; + cmd; + } + else + { + cmd; + cmd; + } +< +間違い: > + if (cond) { + cmd; + cmd; + } else { + cmd; + cmd; + } +< +OK: > + while (cond) + { + cmd; + } +< +間違い: > + while (cond) { + cmd; + } +< +ブロックがコメントを含めて 1 行の場合は、波括弧は省略できる。 +OK: > + if (cond) + cmd; + else + cmd; +< +間違い: > + if (cond) /* - * The "foo" argument does something useful. - * Return OK or FAIL. + * comment */ -新しいコードもしくは変更するコードの行については、// コメント を使うことが好ま -れる。特にコードの後ろに続くコメントなど: - int some_var; // single line comment useful here + cmd; + else + cmd; +< +`if`/`else` の一方のブロックに波括弧がある場合は、もう一方のブロックにも波括弧 +が必要である。 +OK: > + if (cond) + { + cmd; + } + else + { + cmd; + cmd; + } +< +間違い: > + if (cond) + cmd; + else + { + cmd; + cmd; + } + + if (cond) + { + cmd; + cmd; + } + else + cmd; +< +OK: > + while (cond) + cmd; +< +間違い: +> + while (cond) + if (cond) + cmd; +< + + +☆型 *style-types* + +記述的な型を使用すること。それらのリストは src/structs.h ファイル内、またはお +そらく作業中のファイルの typedef 内にある。 + +Note すべてのカスタム型には「_T」という接尾辞が付けられることに注意 + +OK: > + int is_valid_line_number(linenr_T lnum); +< +間違い: > + int is_valid_line_number(unsigned long lnum); +< + + +☆空白と句読法 *style-spaces* + +関数名と括弧の間に空白はない: -列挙型 (Enums) ~ +OK: func(arg); +間違い: func (arg); -列挙型の末尾の要素にコンマ (trailing comma) が付いていてもよい。C89 では認めら -れていなかった。 +`if`, `while`, `switch` 等の後には空白を入れること。 -型 (Types) ~ +OK: if (arg) for (;;) +間違い: if(arg) for(;;) -"long long" は使用してもよく、64 bit を想定している。printf では %lld を使用す -ること。同じように "long long unsigned" では %llu を使用する。 +コンマまたはセミコロンの後に空白を入れる: -宣言 ~ +OK: func(arg1, arg2); for (i = 0; i < 2; ++i) +間違い: func(arg1,arg2); for (i = 0;i < 2;++i) -現在、サポートされている最小限のコンパイラは MSVC 2015 であり、宣言はブロック -の先頭にある必要はない。しかし、多くの場合、とにかくこれを実施することを推奨す -る。 +'=', '+', '/' 等の前後に空白を入れる。 -for ループ変数のループ内宣言を推奨する: - for (int i = 0; i < len; ++i) -これは明確な利点なので、より頻繁に使用することになる。 +間違い: var=a*5; +OK: var = a * 5; +似たような動作をグループ化するには、空行を使う。 -使用してはいけないもの ~ +OK: > + msg_puts_title(_("\n--- Signs ---")); + msg_putchar('\n'); -これらの C99 の機能は、コンパイラのサポートが不十分なため使用してはいけない。 -- 可変長配列 (C11 でもこれはオプショナルな機能である)。 -- _Bool 型と _Complex 型。 -- "inline" (ほとんど必要ない、コンパイラに最適化させよう。) -- フレキシブル配列メンバ: HP-UX C コンパイラはサポートしていない。(John - Marriott) + if (rbuf == NULL) + buf = firstbuf; + else + buf = rbuf; + + while (buf != NULL && !got_int) +< +間違い: > + msg_puts_title(_("\n--- Signs ---")); + msg_putchar('\n'); + if (rbuf == NULL) + buf = firstbuf; + else + buf = rbuf; + while (buf != NULL && !got_int) +< + + +☆関数 *style-functions* + +関数宣言は、戻り値の型を別のインデントされた行に記述して使用する: +OK: > + int + function_name(int arg1, int arg2) + { + } +< +間違い: > + int function_name(int arg1, int arg2) + { + } +< -☆共通関数を使う *style-functions* +関数パラメータに意味のある名前を付ける。 + + +☆共通関数を使う *style-common-functions* よく使われる関数のうち、特別なVimバージョンを持つものがある。これらは理由あっ て導入されたものなので、常にVimバージョンを使うように意識すること。 @@ -315,27 +498,30 @@ get_env_value() Linux システム関数 ☆その他 *style-various* -型の定義に使う名前は最後を "_T" にする: > - typedef int some_T; マクロ定義はすべて大文字にする: > #define SOME_THING +< + 機能に関する定義は "FEAT_" で始める: > #define FEAT_FOO +< '\"' を使わない、あるコンパイラはこれを扱えない。'"' はうまく機能する。 -次を使ってはならない: +以下を使ってはならない: > #if HAVE_SOME +< あるコンパイラはこれを扱えず、"HAVE_SOME" が定義されていないと訴える。 -次を使う +以下を使う > #ifdef HAVE_SOME -または +< +または > #if defined(HAVE_SOME) - +< ☆スタイル *style-examples* -一般的なルール: １行に１つのステートメント。 +１行に１つのステートメント。 間違い: if (cond) a = 1; @@ -353,105 +539,6 @@ OK: do a = 1; while (cond); -間違い: if (cond) { - cmd; - cmd; - } else { - cmd; - cmd; - } - -OK: if (cond) - { - cmd; - cmd; - } - else - { - cmd; - cmd; - } - -ブロックが1行の場合は、波括弧を省くことができる。if/else の1つのブロックに波括 -弧がある場合、他のブロックにも波括弧があると、通常は見栄えが良くなる: -OK: if (cond) - cmd; - else - cmd; - -OK: if (cond) - { - cmd; - } - else - { - cmd; - cmd; - } - -関数宣言には ANSI スタイルを使い、戻り値の型は独立した行にインデントをつけて書 -くこと。 - -間違い: int function_name(int arg1, int arg2) - -OK: /* - * Explanation of what this function is used for. - * この関数が何に使われるかの説明。 - * - * Return value explanation. - * 戻り値の説明。 - */ - int - function_name( - int arg1, // short comment about arg1 - int arg2) // short comment about arg2 - { - int local; // comment about local - - local = arg1 * arg2; - - - -☆空白と区切り *style-spaces* - -関数名とブラケットの間にスペースを入れないこと: - -間違い: func (arg); -OK: func(arg); - -if、while、switchなどの後には、スペースを入れること。 - -間違い: if(arg) for(;;) -OK: if (arg) for (;;) - -コンマ、セミコロンの後にはスペースを入れること: - -間違い: func(arg1,arg2); for (i = 0;i < 2;++i) -OK: func(arg1, arg2); for (i = 0; i < 2; ++i) - -'='、'+'、'/' などの前と後には、スペースを入れること。 - -間違い: var=a*5; -OK: var = a * 5; - -一般的なこと: コードの行をグループ分けするために、空行を使う。行グループのす -ぐ上にコメントを入れる。こうすることによって、何が行われるのかをより簡単に知 -ることができる。 - -OK: /* Prepare for building the table. */ - /* テーブルの作成の準備 */ - get_first_item(); - table_idx = 0; - - /* Build the table */ - /* テーブルの作成 */ - while (has_item()) - table[table_idx++] = next_item(); - - /* Finish up. */ - /* 仕上げ */ - cleanup_items(); - generate_hash(table); ============================================================================== 3. 決定事項 *design-decisions* diff --git a/en/develop.txt b/en/develop.txt index 678a92461..dd8b94d91 100644 --- a/en/develop.txt +++ b/en/develop.txt @@ -1,4 +1,4 @@ -*develop.txt* For Vim version 9.1. Last change: 2024 May 11 +*develop.txt* For Vim version 9.1. Last change: 2024 Oct 31 VIM REFERENCE MANUAL by Bram Moolenaar @@ -157,6 +157,7 @@ VIM IS... NOT *design-not* being less consistent over all platforms. But functional GUI features are welcomed. + ============================================================================== 2. Coding style *coding-style* @@ -171,17 +172,20 @@ MAKING CHANGES *style-changes* The basic steps to make changes to the code: 1. Get the code from github. That makes it easier to keep your changed version in sync with the main code base (it may be a while before your - changes will be included). You do need to spend some time learning git, - it's not the most user friendly tool. + changes will be included). 2. Adjust the documentation. Doing this first gives you an impression of how your changes affect the user. 3. Make the source code changes. 4. Check ../doc/todo.txt if the change affects any listed item. -5. Make a patch with "git diff". You can also create a pull request on - github, but it's the diff that matters. -6. Make a note about what changed, preferably mentioning the problem and the +5. Add a test to src/testdir to verify the new behaviour and ensure it won't + regress in the future. +6. Make a patch with "git diff". +7. Make a note about what changed, preferably mentioning the problem and the solution. Send an email to the |vim-dev| maillist with an explanation and - include the diff. Or create a pull request on github. + include the diff. + +For any non-trivial change, please always create a pull request on github, +since this triggers the test suite. C COMPILER *style-compiler* *ANSI-C* *C89* *C99* @@ -191,52 +195,234 @@ Later standards, such as C99, are not widely supported, or at least not 100% supported. Therefore we use only some of the C99 features and explicitly disallow some (this will gradually be adjusted over time). -Please don't make changes everywhere to use the C99 features, it causes merge -problems for existing patches. Only use them for new and changed code. +Features not to be used ~ + +These C99 features are not to be used, because not enough compilers support +them: +- Variable length arrays (even in C11 this is an optional feature). +- C99 _Bool and _Complex types. +- "inline" (it's hardly ever needed, let the optimizer do its work) +- flexible array members: Not supported by HP-UX C compiler (John Marriott) -Comments ~ -Traditionally Vim uses /* comments */. We intend to keep it that way -for file and function headers and larger blocks of code, E.g.: +COMMENTS *style-comments* + +Try to avoid putting multiline comments inside a function body: if the +function is so complex that you need to separately comment parts of it, you +should probably rethink the structure of the function. + +For file headers and function descriptions use: > + /* + * Description + */ +< +For everything else use: > + // comment +< + + +INDENTATION *style-indentation* + +We use 4 space to indent the code. If you are using Vim to edit the source, +you don't need to do anything due to the |modeline|. + +For other editors an `.editorconfig` is provided at the root of the repo. + + +DECLARATIONS *style-declarations* + +Declare, when possible, `for` loop variables in the guard: +OK: > + for (int i = 0; i < len; ++i) +< +Wrong: > + int i; + for (i = 0; i < len; ++i) +< +Always declare a variable with a default value: +OK: > + int n = 0; + int *ptr = NULL; +< +Wrong: > + int n; + int *ptr; +< + + +BRACES *style-braces* + +All curly braces must be returned onto a new line: +OK: > + if (cond) + { + cmd; + cmd; + } + else + { + cmd; + cmd; + } +< +Wrong: > + if (cond) { + cmd; + cmd; + } else { + cmd; + cmd; + } +< +OK: > + while (cond) + { + cmd; + } +< +Wrong: > + while (cond) { + cmd; + } +< +When a block has one line, including comments, the braces can be left out. +OK: > + if (cond) + cmd; + else + cmd; +< +Wrong: > + if (cond) /* - * The "foo" argument does something useful. - * Return OK or FAIL. + * comment */ -For new code or lines of code that change, it is preferred to use // comments. -Especially when it comes after code: - int some_var; // single line comment useful here + cmd; + else + cmd; +< +When an `if`/`else` has braces on one block, the other should have it too. +OK: > + if (cond) + { + cmd; + } + else + { + cmd; + cmd; + } +< +Wrong: > + if (cond) + cmd; + else + { + cmd; + cmd; + } + + if (cond) + { + cmd; + cmd; + } + else + cmd; +< +OK: > + while (cond) + cmd; +< +Wrong: +> + while (cond) + if (cond) + cmd; +< + + +TYPES *style-types* + +Use descriptive types. You can find a list of them in the src/structs.h file +and probably in a typedef in the file you are working on. + +Note that all custom types are postfixed with "_T" + +OK: > + int is_valid_line_number(linenr_T lnum); +< +Wrong: > + int is_valid_line_number(unsigned long lnum); +< + + +SPACES AND PUNCTUATION *style-spaces* + +No space between a function name and the bracket: + +OK: func(arg); +Wrong: func (arg); + +Do use a space after `if`, `while`, `switch`, etc. + +OK: if (arg) for (;;) +Wrong: if(arg) for(;;) -Enums ~ +Use a space after a comma or semicolon: -The last item in an enum may have a trailing comma. C89 didn't allow this. +OK: func(arg1, arg2); for (i = 0; i < 2; ++i) +Wrong: func(arg1,arg2); for (i = 0;i < 2;++i) -Types ~ +Use a space before and after '=', '+', '/', etc. -"long long" is allowed and can be expected to be 64 bits. Use %lld in printf -formats. Also "long long unsigned" with %llu. +Wrong: var=a*5; +OK: var = a * 5; -Declarations ~ +Use empty lines to group similar actions together. -Now that the minimal supported compiler is MSVC 2015 declarations do not need -to be at the start of a block. However, it is often a good idea to do this -anyway. +OK: > + msg_puts_title(_("\n--- Signs ---")); + msg_putchar('\n'); -Declaration of the for loop variable inside the loop is recommended: - for (int i = 0; i < len; ++i) -Since this is clearly an advantage we'll use this more often. + if (rbuf == NULL) + buf = firstbuf; + else + buf = rbuf; + while (buf != NULL && !got_int) +< +Wrong: > + msg_puts_title(_("\n--- Signs ---")); + msg_putchar('\n'); + if (rbuf == NULL) + buf = firstbuf; + else + buf = rbuf; + while (buf != NULL && !got_int) +< -Not to be used ~ -These C99 features are not to be used, because not enough compilers support -them: -- Variable length arrays (even in C11 this is an optional feature). -- _Bool and _Complex types. -- "inline" (it's hardly ever needed, let the optimizer do its work) -- flexible array members: Not supported by HP-UX C compiler (John Marriott) +FUNCTIONS *style-functions* + +Use function declarations with the return type on a separate indented line. +OK: > + int + function_name(int arg1, int arg2) + { + } +< +Wrong: > + int function_name(int arg1, int arg2) + { + } +< -USE OF COMMON FUNCTIONS *style-functions* +Give meaningful names to function parameters. + + +USE OF COMMON FUNCTIONS *style-common-functions* Some functions that are common to use, have a special Vim version. Always consider using the Vim version, because they were introduced with a reason. @@ -311,27 +497,30 @@ get_env_value() Linux system function VARIOUS *style-various* -Typedef'ed names should end in "_T": > - typedef int some_T; -Define'ed names should be uppercase: > +Define'd names should be uppercase: > #define SOME_THING +< + Features always start with "FEAT_": > #define FEAT_FOO +< Don't use '\"', some compilers can't handle it. '"' works fine. -Don't use: +Don't use: > #if HAVE_SOME +< Some compilers can't handle that and complain that "HAVE_SOME" is not defined. -Use +Use > #ifdef HAVE_SOME -or +< +or > #if defined(HAVE_SOME) - +< STYLE *style-examples* -General rule: One statement per line. +One statement per line. Wrong: if (cond) a = 1; @@ -349,101 +538,6 @@ OK: do a = 1; while (cond); -Wrong: if (cond) { - cmd; - cmd; - } else { - cmd; - cmd; - } - -OK: if (cond) - { - cmd; - cmd; - } - else - { - cmd; - cmd; - } - -When a block has one line the braces can be left out. When an if/else has -braces on one block, it usually looks better when the other block also has -braces: -OK: if (cond) - cmd; - else - cmd; - -OK: if (cond) - { - cmd; - } - else - { - cmd; - cmd; - } - -Use ANSI (new style) function declarations with the return type on a separate -indented line. - -Wrong: int function_name(int arg1, int arg2) - -OK: /* - * Explanation of what this function is used for. - * - * Return value explanation. - */ - int - function_name( - int arg1, // short comment about arg1 - int arg2) // short comment about arg2 - { - int local; // comment about local - - local = arg1 * arg2; - - - -SPACES AND PUNCTUATION *style-spaces* - -No space between a function name and the bracket: - -Wrong: func (arg); -OK: func(arg); - -Do use a space after if, while, switch, etc. - -Wrong: if(arg) for(;;) -OK: if (arg) for (;;) - -Use a space after a comma and semicolon: - -Wrong: func(arg1,arg2); for (i = 0;i < 2;++i) -OK: func(arg1, arg2); for (i = 0; i < 2; ++i) - -Use a space before and after '=', '+', '/', etc. - -Wrong: var=a*5; -OK: var = a * 5; - -In general: Use empty lines to group lines of code together. Put a comment -just above the group of lines. This makes it easier to quickly see what is -being done. - -OK: /* Prepare for building the table. */ - get_first_item(); - table_idx = 0; - - /* Build the table */ - while (has_item()) - table[table_idx++] = next_item(); - - /* Finish up. */ - cleanup_items(); - generate_hash(table); ============================================================================== 3. Design decisions *design-decisions*