はじめに
この記事は iOS Advent Calendar 2023 2 日目の記事になります。
ここでは Xcode のコメントの書き方についてまとめていきます。
なぜコメント？
コメントを笑うものはコメントに泣きます。
行単位のコメント
行単位のコメントは、コメントをしたい箇所に // をつけてコメントを書きます。
// ここにコメントを書く
func hoge() {
ブロックコメント
複数行のコメントを書く際、まとめて書いた方が読みやすくなります。
その場合、ブロックコメントを使うと良いでしょう。
ブロックコメントは、/* と */ でコメントを囲むことによって、複数行のコメントを書くことができます。
/*
ここに
複数行の
コメントを書く
*/
func hoge() {
Document Items
これらのコメントは、コードの読みやすさを向上させ、開発プロセスを効率化するために役立ちます。
特に、大きなプロジェクトやチームでの作業において、これらのコメントはコードのナビゲーションを容易にします。
// MARK
コードのセクションに見出しを追加します。
私はextension や クラス内の enum などを区切る際に使用しています。
// MARK: Private メソッド
func hoge() {
追加すると、フラッグ🚩のようなマークがつきます。
また、minimap を表示すると、//MARK: の内容が表示されます。
ラインをつける
また、このコメントは : の後に - を入れると、ジャンプバーとミニマップセクションの前に区切り線を表示するようになります。
// MARK: - Private メソッド
func hoge() {
// TODO
今後の作業を指示するコメントを追加できます。ジャンプバーでは、TODOコメントがアイコンでハイライトされ、簡単に識別できるようになります。
// TODO: あとで実装する
func hoge() {
追加すると、チェックボックス✅のようなマークがつきます。
でも、大体やらなかったりするものが多いので、なるべく早くやるようにしましょう。
そのため、TODO に期限を書くと良いでしょう。
// TODO: [10/14/2019]
func hoge() {
また、TODO は、後述する FIXME と違って、後でやることを書くだけです。
後でやることがわかっている場合は、FIXME を使いましょう。
// FIXME
FIXME は、コード内の修正が必要な箇所をメモするのに使います。ジャンプバーでは、FIXMEコメントがアイコンで表示されます。
// FIXME: ここにバグがあるので直す
func hoge() {
追加すると、絆創膏🩹のようなマークがつきます。
これも、TODO と同様に期限を書くと良いでしょう。
// FIXME: [10/14/2019]
func hoge() {
// ???
??? は、わからないことを書きます。
正直用途は不明ですが、議論の余地がある場合や、調査が必要な場合に使うと良いでしょう。
// ???: ここの用途が不明
func hoge() {
追加すると、はてな❓マークがつきます。
// !!!
!!! は、注意が必要なことを書きます。
こちらも、用途は不明ですが、注意が必要な場合に使うと良いでしょう。
// !!!: ここに注意が必要
func hoge() {
追加すると、びっくりマーク‼️がつきます。
ドキュメンテーションコメント
JavaDoc のように、ドキュメントを生成するためのコメントです。
対象機能のドキュメントコメントに解説を追加できます。
/// ここにコメントを書く
func hoge() {
このコメントは、⌥+クリック でドキュメントを表示できます。
ドキュメンテーションテンプレートの挿入方法
Xcode には、ドキュメンテーションコメントのパラメータを自動で検出して書き出してくれる機能があります。
メニューバーから Editor > Structure > Add Documentation を選択すると、または、⌥ + ⌘ + / でドキュメンテーションテンプレートが挿入されます。
関数コメントの書き方
関数コメントには、以下のような役割を持ったパーツがあります。
それらを使って、関数の説明を書いていきます。
Parameters: 引数名を説明する
関数の引数について説明を追加します。
使い方は、以下のようになります。
/// - parameter [パラメタ名]: [説明]
or
///- Parameters:
/// - [パラメタ名]: [説明]
/// - [パラメタ名]: [説明]
Returns: 戻り値を説明する
関数の戻り値について説明を追加します。
使い方は以下のようになります。
/// - Returns: [説明]
カスタムパーツ
あらかじめ用意されているパーツ以外にも、ハイフン(-)カスタムパーツを追加できます。
/// - Precondition
/// 前提条件
/// - Postcondition
/// 事後条件
/// - Requires
/// 必要条件
/// - Invariant
/// 不変
/// - Complexity
/// 複雑度
/// - Important
/// 重要
/// - Warning
/// 警告
/// - Author
/// 著者
/// - Authors
/// 著者複数
/// - Copyright
/// コピーらいと
/// - Date
/// 日付
/// - SeeAlso
/// これもみてね
/// - Since
/// いつから
/// - Version
/// バージョン
/// - Attention
/// 注意
/// - Bug
/// バグ
/// - Experiment
/// 実験
/// - Note
/// ノート
/// - Remark
/// 気付き
func hoge() {
Markdown
ドキュメントコメントは、一部 Markdown をサポートしています。
これにより、ドキュメント内で関数の使い方や参考にした URL などを貼ることができます。
/**
# この関数について
この関数は特定の計算を行います。
## 使用方法
`calculateSomething`関数を呼び出し、必要なパラメータを渡します。
### パラメータ
- `param1`: 最初のパラメータ、整数型
- `param2`: 二番目のパラメータ、整数型
### 戻り値
- `Int`: 計算結果を整数で返します。
### 例
```swift
let result = calculateSomething(param1: 5, param2: 3)
print(result)
```
### 参考資料
- [StackOverflow](https://stackoverflow.com/)
*/
func hoge() {
最後に
これらのコメントは、コードの読みやすさを向上させ、開発プロセスを効率化するために役立ちます。
ぜひ、使ってみてください。
参考文献