コードマークとは何ですか？
簡単に言うと、 コードマークとは、コードに関連する議論のことです。 。質問、提案、バグレポート、ドキュメントなどです。これらのディスカッションはすべて、参照するコードブロックに固定されて保存されるため、将来的に活用することができます。チームに新しく加わった開発者、他の人のコードのバグを修正しようとしている開発者、あるいは6ヶ月前に行った変更の理由を思い出そうとしている人など、さまざまな人がいるでしょう。どんな場合でも、CodeStreamは、文脈に沿った方法で議論を表面化させることで、コードの理解を助けます。
ファイルが時間とともに変化しても、コードマークはコードとつながっています。コードブロックの上に新しいコードを追加したり、コードを編集したり、コードブロック全体をファイルの別のセクションにカット＆ペーストしたりすると、コードマークが変更に合わせて移動するのがわかります。
コードマークの作成
コードマークを作成するには、エディターでコードのブロックを選択し、選択したブロックの隣にある「コードストリーム」ペインに表示されるアイコンの1つをクリックします。
IntelliJ などの JetBrains IDE を使用している場合は、コードのブロックを選択したときにエディターのガターに表示される + ボタンを使用してコードマークを作成することもできます。
CodeStream ペインが閉じている場合や表示されていない場合でも、電球またはコンテキスト メニューの CodeStream オプションを使用してコードマークを作成できます。CodeStream ペインの上部にある + メニューを探すこともできます。
IDEに多くの時間を費やしていないチームメイトにアプローチする必要がありますか？あるいは、まだCodeStreamを利用していないチームメイトがいるかもしれません。オプションとして、コードマークをSlackやMicrosoft Teamsで共有することができます。Slackとの連携では、チームメイトがSlackから直接返信することもできます。
コメントコードマーク
コメントコードマークは、あらゆる種類の議論とコードブロックを結びつけるための万能コードマークです。質問をする。提案をする。コードを文書化する。コードベースの重要な部分を記録する。可能性は無限大です。
コードマークの発行
何かを成し遂げなければならないとき、誰かの名前が付いた課題として記録されていれば、それが実現する可能性は高くなります。バグを報告するために課題を割り当てたり、インラインFIXMEではなくトラッキングされた課題として項目を記録することで、技術的負債を管理することができます。
チームが追跡にAsana、Azure DevOps、Bitbucket（クラウド）、GitHub（クラウドまたはエンタープライズ）、GitLab（クラウドまたは自己管理）、Jira（クラウドまたはサーバー）、Linear、Shortcut、Trello、またはYouTrack（クラウド）を使用している場合問題の場合は、CodeStreamから直接これらのサービスの1つに問題を作成できます。コードマークフォームの上部にあるドロップダウンから、使用するサービスを選択します。
選択したサービスで認証プロセスを経た後、課題の送信先を選択します。例えば、Jiraの場合は、適切な課題タイプとプロジェクトを選択します。
CodeStream上で課題が作成されると、外部サービスで作成された課題へのリンクが含まれます。例では、Jira上の課題のURLが表示されています。
Jiraに掲載されている課題には、関連するコードをIDEで開くためのリンクが含まれています。
適切な人を議論に巻き込む
コードマークを作成すると、CodeStreamはあなたがコメントしているコードに最も最近触れた人を自動的に言及します。もちろん、これらのメンションを削除し、必要に応じて他の人を手動でメンションすることもできます。
コードを触った人がまだCodeStreamに参加していない場合もあるかもしれませんが、その場合はCodeStreamがチェックボックスを用意して、メールで通知します。メールに返信することで、コメントがCodeStreamに投稿されます。もちろん、CodeStreamをインストールして、IDEから参加することもできます。
異なるバージョンのコードを扱う
フィーチャーブランチにいるのか、ローカルに変更があるのか、あるいは単にしばらくプルしていないだけなのか。自分が見ているコードと、チームメイトが見ているコードが異なる理由は無数にあります。その結果、コードマークで参照されているコードが、ローカルにあるコードと一致しないことがたくさんあります。
CodeStreamはこのような状況を認識し、コードブロックのオリジナルバージョン（例えば、コードマークが作成された時）、現在のバージョン、そして差分を含んでいます。
CodeStreamを使えば、どんなソースファイルでも、どんなコードでも、いつでも、たとえそれがエディタに入力したばかりで、まだコミットしていないコードであっても、議論することができることに留意してください。CodeStreamは、開発プロセスの最も早い段階からコードについて議論することを可能にします。
コードマークの解消
必須ではありませんが、コメントと問題のコードマークの両方を解決できます。緑、紫、灰色のアイコンは、それぞれオープン、解決済み、アーカイブされたコードマークを表すために使用されます。コードマークを解決すると同時にコメントを追加したり、コードマークを同時にアーカイブしたりすることもできます。
高度な機能
高度な機能としては、複数の範囲コードマーク、ファイルの添付、タグ、関連コードマークなどがあります。
複数のレンジ
コードに関する議論の多くは、1つのコードブロックだけではなく、複数のコードの場所を同時に参照できる場合に、コンセプトを最もよく表現することができます。ここでは、マルチレンジコードマークの例をいくつかご紹介します。
- 関数の名称に影響を与えるような変更が検討されています。関数の呼び出しの各インスタンスは、1つの議論で参照できるようになりました。
- ReactコンポーネントとそのCSSスタイリングがうまく連動していないので、チームに意見を求めたいとします。チームメイトが自分の言っていることを正確に理解できるように、適用すべきと思われるdivとCSSルールを選択するとよいでしょう。
- サーバーへのAPIコールを行うクライアントが、予期しない結果を得ることがあります。APIコールを行っているコードと、APIサーバーのハンドラーを選択して、2つのアクションを結びつけてください。
マルチレンジコードマークを作成するには、 + コードブロックの追加 をクリックします。
次に、同じファイルや別のファイル、あるいは別のレポから別のコードブロックを選択します。
次の例のように、それぞれを[#N]と呼ぶことで（またはコードブロックの1つからピンアイコンをクリックしてマークダウンを挿入することで）、投稿に異なるコードブロックを散在させることができます。
その例がどのようにレンダリングされるかを説明します。
コードマークを作成した後、各コードブロックの右下にあるジャンプアイコンをクリックすることで、異なる場所にジャンプすることができます。
コードマークを編集する際には、コードブロックを追加・削除することができ、破線の四角いアイコンをクリックすることで、コードブロックの位置を変更することができます。
添付ファイル
コードブロックに直接ファイルを添付することで、コードに関する議論をより豊かにすることができます。ファイルを添付することで、コメントやドキュメントがどれだけ説得力のあるものになるか考えてみてください。
- 新機能の開発の指針となる仕様書。
- コード内の問題のデバッグに役立つログファイルです。
- UI作業を明確にするためのモックアップです。
- 問題点を強調するためのスクリーンショット。
コードのコメントや課題を作成する際に、説明欄にドラッグ＆ドロップするか、クリップボードから貼り付けるか、クリップアイコンをクリックすることで、ファイルを添付することができます。
マークダウンを使って画像をインラインで表示することもできます。添付ファイルの右にあるピンのアイコンをクリックすると、CodeStreamがマークダウンを挿入してくれます。
これで、あなたが何を求めているのかが、チームメイトに正確に伝わります。
添付ファイル欄のファイルをクリックすると、ダウンロードするか、適切なアプリケーションで開くことができます。
タグの追加
コードマーク作成ボックスの中にあるタグのアイコンを見て、タグを選択するか、色とテキストラベルを自由に組み合わせてタグを作成することができます。
タグは、組織のコードマークを大まかに整理してグループ化するのに最適な方法で、ここでの可能性は無限です。
また、 Filter& Search page でタグによる絞り込みも可能です。
関連コードマーク
コードマーク作成フォームのコードストリームアイコンをクリックすると、関連する他のコードマークを選択して、現在のコードマークに添付することができます。これにより、コードベースの異なる部分間の接続が確立されます。例えば、コードベースのある部分を変更すると、別の部分にも変更が必要になる場合、2つの関連するコードマークを作成することで依存関係を識別します。
関連するコードマークを追加すると、それらは関連セクションに表示され、いずれかをクリックすると、そのコードマークとコードの対応するセクションにジャンプできます。
コードマークの管理
任意のコードマークの楕円形メニューをクリックすると、コードマークを管理するためのオプションが表示されます。
- 共有: コードマークを作成した時点でSlackやTeamsに共有するだけでなく、後からいつでも共有することができます。
- フォロー/アンフォロー: コードマークをフォローすると、そのコードマークが更新されたときに通知されます。フォローを解除すると、通知を受け取らなくなります。
- Copy link [リンクをコピー]: コメントのパーマリンクを取得して、どこでも共有できます。誰かがパーマリンクをクリックすると、Web を通じて自動的に IDE にリダイレクトされ、そこでディスカッションが自動的に開かれます。
- Archive [アーカイブ]: 特定のファイル内に永続的に表示するほど重要ではないと思われるコードマークがあるが、完全に削除したくない場合は、代わりにアーカイブすることができます。
- 編集: コードマークの作者のみが編集できます。
- 削除: コードマークの作者のみが削除できますが、そのコードマークが今後価値を持たないと確信できる場合を除き、削除ではなくアーカイブすることをお勧めします。
- Inject as Inline Comment: 特定のコードマークをレポの一部にしたい場合は、このオプションを使ってインラインコメントとして追加します。適切なフォーマットを選択し、タイムスタンプや返信を含めるかどうか、コメントを80文字で折り返すかどうかを指定します。また、インラインコメントとして追加されたコードマークをアーカイブするかどうかも選択できます。
- コードマークの再配置: ほとんどの場合、コードマークは、ファイルが時間の経過とともに変化しても、それが参照するコードブロックに自動的にリンクされたままになります。例えば、コードブロックを切り取って、ファイルの別の場所に貼り付けると、コードマークも一緒に移動します。しかし、コードストリームが自動的に処理できないシナリオもあります。例えば、コードのブロックを別のファイルに貼り付けた場合です。このような場合、 Reposition のコードマークで、コードマークが正しく表示されるようにコードブロックの新しい位置を選択することができます。