HTML-CSS

コメントアウトについて、勉強したことのまとめ。

コメントとは

コメントは、プログラムのソースコード上で、「実行させない部分」のこと。

コードの注釈にあたり、規定のコメントタグで括って「コメントアウトする」。

コメント化された部分は、プログラムとは関係なく自由に記述することができる。

コードを記述している時はその内容を把握していても、後で読み返してみてよくわからなくなってしまうこともある。

そのようなときに、コメントがあるとわかりやすい。

 

特に、オリジナルの関数やクラスのメソッドなどに、引用や返り値などに関するコメントを記述しておき、本人だけでなく関係者全員が内容を把握できるようにする(DocComment)。

 

また、プログラムのソースコードを部分的に修正する場合に、消したい内容を実際に消してしまうのではなく、コメント化することで一時的に機能しないようにする。

これにより、コメント化記号を外すだけで、再度コードを実行させることができる。

 

コメントタグは、言語によって異なる。

  <!-- --> /* */ // #
HTML
CSS
JavaScript
PHP
.htaccess

HTML・XHTMLのコメントアウト

HTMLのコメント

非表示にしたい部分を <!-- --> で括る。

<!-- (1行)HTMLのコメントアウト -->
<!-- (複数行)HTMLは1行でも複数行でも コメントアウトの書き方は同じ -->

ブロックをまとめてコメントアウトしたい場合

例えば、<div>タグなどで囲まれたブロックの中に、すでに <!--コメント--> が使われている場合、うまくコメントアウトできない。

<div class="comment">
<!--コメントしたい-->
<p>ブロック毎コメントアウトしたい</p>
</div>

そんな時に使用する方法2つ。

方法1: style タグを使う

<style>
<div class="comment">
<!--コメントしたい-->
<p>ブロック毎コメントアウトしたい</p>
</div>
</style>

方法2: script タグを使う

<script>
<div class="comment">
<!--コメントしたい-->
<p>ブロック毎コメントアウトしたい</p>
</div>
</script>

CSSのコメントアウト

CSSのコメント

非表示にしたい部分を /* */ で括る。

/*(1行)CSSのコメントアウト */
/* (複数行)CSSは1行でも複数行でも コメントアウトの書き方は同じ */

PHPのコメントアウト

PHPのコメント

PHPのコメントは3種類(1行用2種類と複数行用1種類)

  • #  単一行のコメント
  • // 単一行のコメント
  • /* */ 複数行のコメント

# (シャープ記号)でコメントアウト

単一行用のコメント。 #部分から行の終わりまでがコメントアウトになる。

# (1行)PHPのコメントアウト
# この行もコメントアウト
# この行もコメントアウト

でも、 # はあまり推奨されず、次の // の方が推奨される。

// (スラッシュ記号)でコメントアウト

単一行用のコメント。

//部分から行の終わりまでがコメントアウトになる。

改行または、PHP終了タグ?>がでるまでコメント化が続く。

それ以降はコメント化が解除されて、コードが実行表示になる。

// (1行)PHPのコメントアウト
// この行もコメントアウト
// この行もコメントアウト

/* */ でコメントアウト

複数行用のコメント。 /(スラッシュ記号)*(アスタリスク記号)で括り、コメントアウトする。 /*から始まり、*/で閉じるところまでがコメントアウトされる。

/* (複数行)PHPは1行と
複数行で異なる */

PHPのタグ<?PHP ?>を跨いでのコメントアウトも可能。

HTMLが絡んだ場合のコメント

HTML内に埋め込まれたPHPコードでPHPのコメントを使用する場合、コメントアウトしたい範囲を <?php と ?> で括り(PHPブロック)、PHPのコメント/* */を利用するとよい。

この方法で、HTMLに埋め込まれたPHPコードもまるごとコメントアウトできる

<?php /* コメントアウトされる。
<?php echo 'ここもコメントアウトされる。'; ?>
*/
?>

PHPブロックについて

PHPはHTMLに組み込まれる事が多い。 その場合、「PHPブロック」と呼ばれるブロックで括る。

  • 開始タグ:<?php
  • 終了タグ:?>
<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="utf-8">
<title>PHPブロックを使用</title>
</head>
<body>
<?php echo 'ここがPHPブロック'; ?>
</body>
</html>

上記の場合、 <?php と ?> で括った "echo 'ここがPHPブロック'; が、PHPプログラム。

※ 'echo' は文字力を出力する言語構造。

感覚として覚えておくべきは、PHPブロックの外側はHTMLで、PHPブロックの内側はPHPだということ。

ちなみに、PHPブロックで終了するファイルは、PHPブロックの終了タグを書かない、というルールがある。

<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="utf-8">
<title>PHPブロックで終わる場合</title>
</head>
<body>
</body>
<?php echo "</html>";
※ 上記の場合、PHPブロックで終わっているので、 ?> は書かない。

コメントアウトのエラー

コメントがネスト(入れ子)になっている

PHPのコメント/* */はネストできない。 最初に現れた閉じタグですべて閉じられてしまう。

/* echo 'コメントアウトされる。';
/* echo 'コメントアウトされる。'; */ 
echo '前の閉じタグで閉じられたので、コメントアウトできない'; */

ネストする場合は、//#を使用する。

<?php /* echo 'Hello!'; // ネストコメント */ ?>
<?php /* echo 'Hello!'; # ネストコメント */ ?>

PHPタグの外でコメントしている

PHPのコメントアウトはPHPタグ内でしか効果がない。

/* <?php
echo 'PHPタグの外でコメントアウトしているので、コメントアウトされない';
?> */

<?php
/* echo 'PHPタグの中だったらコメントアウトされる'; */
?>

PHPなのにHTML etc. 用のコメントを使用している。

PHPタグ内でHTMLのコメントで括ると、当たり前だがコメントアウトされない。

<?php
<!-- echo HTMLのコメントタグではコメントアウトされない; -->
?>

<?php
/* echo 'PHPのコメントタグを使えばコメントアウトされる'; */
?>

HTMLコードも含めてPHPのコメント//を使用している

PHPのコメントでも、HTMLとPHPをまとめて//でコメントアウトすると、1行でもPHPの閉じタグ以降はコメントアウトされない。

この場合は、1行でも/* */のコメントタグを使用する。

<?php //コメントアウトされる。<?php echo 'でも…'; ?> ←PHPの閉じタグ以降はコメントアウトされない
?>

<?php /*コメントアウトされる。<?php echo 'ここも…'; ?> コメントアウトされる*/
?>

※ PHPはHTMLに埋め込んで記述することも多いため、うっかりPHPタグの外で/* */のコメントタグを使っていたり、PHPの中で<!-- -->のコメントタグを使っていたりすることがないよう、注意する。

コメントを含んだPHPソースをまとめてコメントアウト

eg. 以下のようなコメントアウトを含んだソースを一気に全部コメントアウトする場合、

<?php
// ここはコメントアウト
// ここもコメントアウト
// そしてここもコメントアウト

/* */で一気にコメントアウトが可能。

<?php
/*
// ここはコメントアウト
// ここもコメントアウト
// そしてここもコメントアウト
/*

※ 普段は//で1行コメントアウトしておいて、あとから必要な部分を/* */でまとめてコメントアウトする習慣をつけておくと良い。

DocComment

DocCommentは、関数やクラスなどを就職する、特別な形態の範囲コメント。

/** */

で括る。

以下は、DocCommentの例色々 ↓

ファイルの先頭

説明文章を完結に記述

<?php
/**
* ファイルの説明
* @copyright 会社名
* @license ライセンス
* @author 作成者 <メールアドレス>
* @link資料
*/

クラス

/**
* クラスの説明。 *
* 1行開けて、もう少し詳しく説明することもできる。 *
* @access アクセスレベル
* @author 作成者 <メールアドレス>
* @package パッケージ名
* @copyright 会社名
* @category カテゴリー
* @since PHP7.1
* @version プログラムバージョン
* @pacage パッケージ */

関数・メソッド

@paramで関数の引数を記述できる。

@returnで関数が返す型を記述できる。

regurnが複数の型を返す場合はstring|booleanなどと記述する。

/**
*関数/メソッド名
*処理内容
*作成日
*
*@param string $str 第一引数
* @param integer $num 第二引数
* @return array 戻り値の
*/

変数

@varタグで変数の型を明示できるが、メソッドの戻り値の型が不明な場合にのみ記述するほうがよいらしい。

/**
@var string 名前
*/

$name;

JavaScriptのコメントアウト

JavaScriptのコメントアウト

PHPのコメントは2種類(1行用1種類と複数行用1種類)

  • // 単一行のコメント
  • /* */ 複数行のコメント

単一行のコメント

// 足し算の関数
function add (a,b) {
return a + b
};

複数行のコメント

/* 足し算の関数
引数: a ,b 戻り値: a+b */

function add (a,b) {
return a + b
};

.htaccessのコメントアウト

.htaccessのコメント

.htaccessのコメントは、 # のみ。

単一行しか使えない。

行の途中でも、" " で括る事でコメントコメントをつけることは可能。

ただじ、Apacheのバージョンや、記述場所によってはエラーになるため、コメント行は基本独立させたほうが良い。

# こんな感じでコメントアウト
# 一行ずつコメントアウトする必要がある

DirectoryIndex
index.html "# 行の途中コメントは基本避ける"

References