CodeStreamでコードを議論する

コードマークとは何ですか？

簡単に言うと、 コードマークとは、コードに関連する議論のことです。 。質問、提案、バグレポート、ドキュメントなどです。これらのディスカッションはすべて、参照するコードブロックに固定されて保存されるため、将来的に活用することができます。チームに新しく加わった開発者、他の人のコードのバグを修正しようとしている開発者、あるいは6ヶ月前に行った変更の理由を思い出そうとしている人など、さまざまな人がいるでしょう。どんな場合でも、CodeStreamは、文脈に沿った方法で議論を表面化させることで、コードの理解を助けます。

ファイルが時間とともに変化しても、コードマークはコードとつながっています。コードブロックの上に新しいコードを追加したり、コードを編集したり、コードブロック全体をファイルの別のセクションにカット＆ペーストしたりすると、コードマークが変更に合わせて移動するのがわかります。

ここでは、チームがコードマークを使ってIDEでコードを共同作業する様子を短いビデオ（3分15秒）で紹介しています。

コードマークスの概要

CodeStreamペインのcodemarksセクションには、現在のリポジトリにあるすべてのコードマークが一覧表示され、簡単に参照できるようになっています。

コードマーク欄の各項目をクリックすると、その詳細やディスカッションを確認することができます。プルリクエストコメント以外は、右側の吹き出しに返信数が表示されます。

デフォルトでは、現在のリポジトリのすべてのコードマークが表示されますが、フィルターを変更して、現在のブランチのすべてのコードマーク、現在のフォルダーのコードマーク、または現在選択されているファイルのコードマークを表示することができます。

フィードバックやプルリクエストのコードマークは、現在のファイルフィルターを選択したときにのみ表示されます。

コードマークの項目の見出しにカーソルを合わせると、右に以下のアイコンが表示されます。

codemarksヘッダーには、コードのコメントや問題を作成するためのオプションが含まれています。また、コードマークをリストではなく、空間ビューで表示することもできます。ディスカッションは、参照しているコードのブロックと一緒に表示され、ソースファイルをスクロールするとディスカッションもスクロールします。

歯車のアイコンをクリックすると、リストをさらにコントロールできます。

• 複数行のコメントを折り返す: コードマークの一部を切り取って表示するのではなく、リストでは投稿全体が表示されます。
• Show tags: 適用可能なタグは各コードマークと共に表示されます。
• コメントを でソート : デフォルトでは、Codemarks は日付順に並んでいますが、フィルタがカレントファイルに設定されている場合は、行番号（ファイル内での順番など）でソートすることができます。
• エディターの溝にアイコンを表示: コードマークは、コードマークセクションのリストに表示されるだけでなく、エディターの溝にアイコンで表示され、参照しているコードブロックと一緒に表示されます。どの種類のコードマークを、どのステータスで表示するかを決定できます。デフォルトでは、フィードバックリクエストのコードマークは表示されますが、プルリクエストのコメントは表示されません。また、解決済みのコードマークはデフォルトで表示されますが、アーカイブされたコードマークは表示されません。

コードマークの作成

コードマークを作成するには、エディターでコードのブロックを選択し、選択したブロックの隣にある「コードストリーム」ペインに表示されるアイコンの1つをクリックします。

IntelliJなどのJetBrains IDEを使用している場合、コードのブロックを選択するとエディタのガッターに表示される + ボタンを使ってコードマークを作成することもできます。フィードバック・リクエストやプル・リクエストのために差分を表示しているときにも、ガッターにカーソルを合わせるとボタンが表示され、1行のコメントを簡単に書くことができます。

コードストリーム」ペインが閉じていたり、表示されていない場合でも、ライトバルブメニューまたはコンテキストメニューの「コードストリーム」オプションを使ってコードマークを作成することができます。

また、CodeStream ペインの上部にある + メニューを探してみてください。

IDEに多くの時間を費やしていないチームメイトにアプローチする必要がありますか？あるいは、まだCodeStreamを利用していないチームメイトがいるかもしれません。オプションとして、コードマークをSlackやMicrosoft Teamsで共有することができます。Slackとの連携では、チームメイトがSlackから直接返信することもできます。

コメントコードマーク

コメントコードマークは、あらゆる種類の議論とコードブロックを結びつけるための万能コードマークです。質問をする。提案をする。コードを文書化する。コードベースの重要な部分を記録する。可能性は無限大です。

コードマークの発行

何かを成し遂げなければならないとき、誰かの名前が付いた課題として記録されていれば、それが実現する可能性は高くなります。バグを報告するために課題を割り当てたり、インラインFIXMEではなくトラッキングされた課題として項目を記録することで、技術的負債を管理することができます。

あなたのチームが課題のトラッキングにAsana、Azure DevOps、Bitbucket (cloud)、Clubhouse、GitHub (cloud or Enterprise)、GitLab (cloud or Self-Managed)、Jira (cloud or Server)、Linear、Trello、またはYouTrack (cloud)を使用している場合、CodeStreamから直接これらのサービスに課題を作成することができます。コードマークフォームの上部にあるドロップダウンから、使用しているサービスを選択します。

選択したサービスで認証プロセスを経た後、課題の送信先を選択します。例えば、Jiraの場合は、適切な課題タイプとプロジェクトを選択します。

CodeStream上で課題が作成されると、外部サービスで作成された課題へのリンクが含まれます。例では、Jira上の課題のURLが表示されています。

Jiraに掲載されている課題には、関連するコードをIDEで開くためのリンクが含まれています。

適切な人を議論に巻き込む

コードマークを作成すると、CodeStreamはあなたがコメントしているコードに最も最近触れた人を自動的に言及します。もちろん、これらのメンションを削除し、必要に応じて他の人を手動でメンションすることもできます。

コードを触った人がまだCodeStreamに参加していない場合もあるかもしれませんが、その場合はCodeStreamがチェックボックスを用意して、メールで通知します。メールに返信することで、コメントがCodeStreamに投稿されます。もちろん、CodeStreamをインストールして、IDEから参加することもできます。

異なるバージョンのコードを扱う

フィーチャーブランチにいるのか、ローカルに変更があるのか、あるいは単にしばらくプルしていないだけなのか。自分が見ているコードと、チームメイトが見ているコードが異なる理由は無数にあります。その結果、コードマークで参照されているコードが、ローカルにあるコードと一致しないことがたくさんあります。

CodeStreamはこのような状況を認識し、コードブロックのオリジナルバージョン（例えば、コードマークが作成された時）、現在のバージョン、そして差分を含んでいます。

CodeStreamを使えば、どんなソースファイルでも、どんなコードでも、いつでも、たとえそれがエディタに入力したばかりで、まだコミットしていないコードであっても、議論することができることに留意してください。CodeStreamは、開発プロセスの最も早い段階からコードについて議論することを可能にします。

コードマークの解消

必須ではありませんが、コメントと課題のコードマークはどちらも解決することができます。 コードストリーム」ペインの「コードマーク 」セクションでは、コードマークを「オープン」、「解決」、「アーカイブ」に分けています。これらの異なる状態を表すために、緑、紫、グレーのアイコンが使用されています。CodeStream」ペインに多くのオープン/グリーンのコードマークが表示されている場合は、チームメイトが解決されていない議論や問題に阻まれていることを意味します。

コードマークを解決すると同時にコメントを追加したり、コードマークをアーカイブすることもできます。

高度な機能

高度な機能としては、複数の範囲コードマーク、ファイルの添付、タグ、関連コードマークなどがあります。

複数のレンジ

コードに関する議論の多くは、1つのコードブロックだけではなく、複数のコードの場所を同時に参照できる場合に、コンセプトを最もよく表現することができます。ここでは、マルチレンジコードマークの例をいくつかご紹介します。

• 関数の名称に影響を与えるような変更が検討されています。関数の呼び出しの各インスタンスは、1つの議論で参照できるようになりました。
• ReactコンポーネントとそのCSSスタイリングがうまく連動していないので、チームに意見を求めたいとします。チームメイトが自分の言っていることを正確に理解できるように、適用すべきと思われるdivとCSSルールを選択するとよいでしょう。
• サーバーへのAPIコールを行うクライアントが、予期しない結果を得ることがあります。APIコールを行っているコードと、APIサーバーのハンドラーを選択して、2つのアクションを結びつけてください。

マルチレンジコードマークを作成するには、 + コードブロックの追加 をクリックします。

次に、同じファイルや別のファイル、あるいは別のレポから別のコードブロックを選択します。

次の例のように、 [#N] のように各コードブロックを参照することで（またはコードブロックの1つからピンのアイコンをクリックしてマークダウンを挿入することで）、差分のコードブロックをあなたの投稿にちりばめることができます。

その例がどのようにレンダリングされるかを説明します。

コードマークを作成した後、各コードブロックの右下にあるジャンプアイコンをクリックすることで、異なる場所にジャンプすることができます。

コードマークを編集する際には、コードブロックを追加・削除することができ、破線の四角いアイコンをクリックすることで、コードブロックの位置を変更することができます。

添付ファイル

コードブロックに直接ファイルを添付することで、コードに関する議論をより豊かにすることができます。ファイルを添付することで、コメントやドキュメントがどれだけ説得力のあるものになるか考えてみてください。

• 新機能の開発の指針となる仕様書。
• コード内の問題のデバッグに役立つログファイルです。
• UI作業を明確にするためのモックアップです。
• 問題点を強調するためのスクリーンショット。

コードのコメントや課題を作成する際に、説明欄にドラッグ＆ドロップするか、クリップボードから貼り付けるか、クリップアイコンをクリックすることで、ファイルを添付することができます。

マークダウンを使って画像をインラインで表示することもできます。添付ファイルの右にあるピンのアイコンをクリックすると、CodeStreamがマークダウンを挿入してくれます。

これで、あなたが何を求めているのかが、チームメイトに正確に伝わります。

添付ファイル欄のファイルをクリックすると、ダウンロードするか、適切なアプリケーションで開くことができます。

タグの追加

コードマーク作成ボックスの中にあるタグのアイコンを見て、タグを選択するか、色とテキストラベルを自由に組み合わせてタグを作成することができます。

タグは、組織のコードマークを大まかに整理してグループ化するのに最適な方法で、ここでの可能性は無限です。

また、 Filter& Search page でタグによる絞り込みも可能です。

関連コードマーク

コードマーク作成フォームのコードストリームアイコンをクリックすると、関連する他のコードマークを選択して、現在のコードマークに添付することができます。これにより、コードベースの異なる部分間の接続が確立されます。例えば、コードベースのある部分を変更すると、別の部分にも変更が必要になる場合、2つの関連するコードマークを作成することで依存関係を識別します。

関連するコードマークを追加すると、それらは関連セクションに表示され、いずれかをクリックすると、そのコードマークとコードの対応するセクションにジャンプできます。

コードマークの管理

任意のコードマークの楕円形メニューをクリックすると、コードマークを管理するためのオプションが表示されます。

• 共有: コードマークを作成した時点でSlackやTeamsに共有するだけでなく、後からいつでも共有することができます。
• フォロー/アンフォロー: コードマークをフォローすると、そのコードマークが更新されたときに通知されます。フォローを解除すると、通知を受け取らなくなります。
• コピーリンク: コードマークの パーマリンク を取得して、どこでも共有することができます。
• アーカイブ: もし、あるファイルに永久に表示するほど重要ではないと思うが、完全に削除したくないコードマークがある場合、代わりにアーカイブにすることができます。 コードマークセクション の設定により、アーカイブされたすべてのコードマークを簡単に確認することができます。
• 編集: コードマークの作者のみが編集できます。
• 削除: コードマークの作者のみが削除できますが、そのコードマークが今後価値を持たないと確信できる場合を除き、削除ではなくアーカイブすることをお勧めします。
• Inject as Inline Comment: 特定のコードマークをレポの一部にしたい場合は、このオプションを使ってインラインコメントとして追加します。適切なフォーマットを選択し、タイムスタンプや返信を含めるかどうか、コメントを80文字で折り返すかどうかを指定します。また、インラインコメントとして追加されたコードマークをアーカイブするかどうかも選択できます。
• コードマークの再配置: ほとんどの場合、コードマークは、ファイルが時間の経過とともに変化しても、それが参照するコードブロックに自動的にリンクされたままになります。例えば、コードブロックを切り取って、ファイルの別の場所に貼り付けると、コードマークも一緒に移動します。しかし、コードストリームが自動的に処理できないシナリオもあります。例えば、コードのブロックを別のファイルに貼り付けた場合です。このような場合、 Reposition のコードマークで、コードマークが正しく表示されるようにコードブロックの新しい位置を選択することができます。

どこでも共有できるパーマリンク

CodeStreamで認証された後、誰かがパーマリンクをクリックすると、自動的にWeb経由でIDEにリダイレクトされ、そこでディスカッションが自動的に開かれます。コメントや問題の場合、ソースファイルが開き、対応するコードブロックまでスクロールします。

CodeStreamは、どのIDEを開くかを決定するために最善を尽くしますが、主に最後にCodeStreamにアクセスしたときに使用したIDEに基づいています。しかし、いつでも開いた Web ページに戻り、使用したい IDE を選択することができます。選択した内容は、次回同じリポジトリに関連したディスカッションを開いたときに記憶されます。

JetBrains IDE を使用している場合は、 Toolbox アプリ をインストールし、CodeStream が IDE にディープリンクできるようにします。

コードブロックのパーマリンク

コードのブロックに必ずしもコメントしたいわけではなく、チームメイトと簡単にコードを共有したい場合もあります。CodeStreamのパーマリンクは、ファイル内の別の場所に移動しても、常に問題のコードを指し示す生きたリンクです。

エディタでコードを選択し、 Get Permalink ボタンをクリックすると、そのコードのパーマリンクが取得できます。

• パーマリンクをパブリックにするか、プライベートにするかを決めます。プライベートのパーマリンクでは、コードを表示する前にCodeStreamの認証が必要になります。
• パーマリンクをコピーして、コードのブロックを共有したい場所に貼り付けてください。
• コメントや課題、フィードバックリクエストと同様に、パーマリンクをクリックすると、自動的にウェブ上のIDEにリダイレクトされ、ソースファイルが開かれ、対応するコードブロックまでスクロールされます。