(X)HTML, XML のコメント記述位置
コメントの記述位置について以下のようなエントリーを目にしましたが、目から鱗です。というか、未熟にも今まで気づきませんでした。(- -;;ゞ
コメントは、対象となる要素の中に記述すべし
デザイナさんにより書き方はいろいろあるかもしれないが、
<!-- hoge start --> <div id="hoge"> // 中身 </div> <!-- hoge end -->こうじゃなくて、
こうしてほしい。
<div id="hoge"> // 中身 <!-- /hoge --> </div>divの中に終了を示すコメント入れなくてどーする！（構造を考えてみれば分かることですよね？）
コレ、論理構造の妥当性の面もそうですが、内部構造を、XSLT やら DOM やらで操作する時に、決定的な違いが出てきますよね。
悪いコメントの記述位置
たとえば、以下のようなコードを書いたとします。見ての通り、コメントは、対象となる要素の外（ここでは前）に記述されています。（かくいう僕もそうでしたけど、以下の例のように、コメントを対象要素外に記述してしまう方って、意外に多いのではないでしょうか？）
bad example: before replacing elements
<div class="section index">
<!-- ここから要旨 -->
<div class="section abstract">
<!-- ここから本編 -->
<div class="section contents">
でも、後になってやっぱり「要旨」は「目次」よりも前の方がいいよなと思い直して、サイト内のすべてのページの構造を変更することになって、index クラスを持った div 要素と、abstract クラスを持った div 要素の位置を入れ替えることになったとします。方法は XSLT でも DOM でも XQuery でも何でもいいですが、とにかく、このまま実行すると、以下のようにコメントと構造のセマンティクスが対応しなくなってしまいます。
bad example: after replacing elements
<div class="section abstract">
<!-- ここから要旨 -->
<div class="section index">
<!-- ここから本編 -->
<div class="section contents">
プログラマーやエンジニアからしてみたら、確かにこれはイライラの元になるでしょうね。文書構造を操作するたびに、内部構造とコメントのミスマッチが生まれる可能性におびえなくてはならないわけですから。（プログラマーかデザイナーかに関わらず、意味不明なコメントほど、ソースコードを見る者を困惑させるものはありませんし。）
良いコメントの記述位置
そこで次のように、コメントを、コメント対象となる要素の中に記述します。こうすることで、後になって構造を操作しても、コメントと構造の関係が対応したまま保持されます。
better example: before replacing elements
<h2>目次</h2>
<div class="section abstract">
<h2>要旨</h2>
<div class="section contents">
<h2>本編の見出し</h2>
better example: after replacing elements
<h2>要旨</h2>
<div class="section index">
<h2>目次</h2>
<div class="section contents">
<h2>本編の見出し</h2>
これは個人的にとても勉強になりました。自分の恥をさらすようですけど、
とか、平気で書いてましたから..。<title>foo</title><!-- ページタイトル -->
範囲指示コメント
- startのコメントは不要（それはdivでいいから）
- いちいち「hoge end」とか書くのはダルいので「/hoge」でいいんじゃね？（これは別にどっちでもいいんだけども）
このあたりは、多少、好みが入りうる余地がある部分なので、絶対こうすべきだ！というルールはないんですが、個人的に若干異論があったので、蛇足かもしれませんが書き留めておきます。
コメントというのは、原則として WYSIWYG なオーサリングソフトではなく、直接ソースコードをテキストエディタで編集、ないし目視チェックする人のためのものでしょうから、終点（ここでは end）よりも始点（同じく start）に記述する方が、特に長くて複雑な（というか構造の深い）コードを記述している場合には、より better な感じがします。なぜって、対応する始点をいちいち遡って確認し直すのに余計なひと手間が掛かりますし、メモ帳やテキストエディットのような構造をパースできないエディタを使っている場合、目視によって構造を判断することになるので、始点の位置を間違えるリスクが生じるからです。
あと、これはおそらく kdmsnr さんに言ってもしょうがない話になってしまうかもしれませんが、始点はともかく、なぜ終点にコメントをつける必要があるのか、イマイチ僕には分かりません。強いて終点を（もしくは始点と終点の両方を）記述するのに意味があるケースがあるとすれば、それはマークアップすることでツリー構造が崩れてしまうようなケースくらいでしょうか。本で例えれば、本の論理的な構造（章・節など）と、媒体や組版上の構造（行やページなど）を同時にマークアップしようとすると、1ページ内に前節と後節の内容がまたがってしまったりして、ツリー構造が崩れてしまう..とか。（HTML に wbr 要素や br 要素があるのはこのため。Page Break に相当する要素は残念ながらありませんけど。）
ツリー構造が崩されるようなケース
<!-- P.24 ここまで -->
<!-- P.25 ここから -->
（ 内容）
<!-- P.25 ここまで -->
<!-- P.26 ここから -->
（ 内容）
<div class="section">
<!-- P.26 ここまで -->
<!-- P.27 ここから -->
（ 内容）
（この場合（本のページ数とセクション数の場合）は、始点か終点のどちらか一方のみの記述でもOK。ただし、ページの範囲を <div class="page">〜</div> のような形でマークアップしてしまうと、ツリー構造が崩れてしまう。）
もっとも、コメントの記述位置同様、単に僕が気づいてない｜知らないだけなのかもしれないので、もしこれという理由がある方は、一見些末に思えるようなことでも結構ですので、是非是非、お教えくださいませ。
ただ、本節の最初にも言ったように、このあたりは好みが入りうる余地がある部分で、要するに重要なのは、制作チームが内部的にコーディングルールを共有することという部分になるのかな..と。
追記（2007-01-23）
恥の上塗りになってしまいますが、元エントリーの kdmsnr さんの想定されていたコメントのユースケースを取り違ってしまったようです。kdmsnr さんが想定されていたのは、（中身を少し分かりやすく書き換えてますが）以下のような id や class のついている要素の始点・終点の頭出し用コメントでした。
<!-- end [div id="foo"] -->
確かに、このユースケースだと、終点にコメントを入れることで、エディタの検索機能で <div id="foo"> の開始位置と終了位置を簡単に頭出しできますよね。しかも "div id="foo" で普通に文字列検索をかければいいだけなので、エディタにパース機能がついている必要もありませんし。大変失礼しました。(- -;;ゞ
一応、想定していたユースケースが違うということもあるので、当初の内容はそのまま保持しておきますが、kdmsnr さんの意図していたところとは、ポイントが少しズレている点をご了承おきくださいませ。
| 固定リンク
「［Web］XHTML」カテゴリの記事
- HTML の見出しをめぐる議論(2007.07.11)
- Re: XHTML+CSS (r)evolution, 3rdの内容は信ずるに値するか?(2007.06.03)
- 論理構造を文脈に読み換えながら class 名を考える(2007.05.30)
- 定義リストの違和感（続）(2007.05.28)
- 定義リストの違和感(2007.05.26)
この記事へのコメントは終了しました。
コメント
↓これだとわからないでしょ（笑）
<div id="hoge1">
<div id="hoge2">
// 中身
<!-- end [div id="hoge2"] -->
</div>
<!-- end [div id="hoge1"] -->
</div>
投稿: floral | 2007-01-23 22:14
kdmsnr さんのエントリーのコメントにある、
<div id="hoge">
// 中身
<!-- end [div id="hoge"] -->
</div>
のようなケースですね。なるほど。っていうか、kdmsnr さんが意識されていたコメントのユースケースを完全に取り違ってましたね、僕。大変 失礼しました。(- -;;ゞ
投稿: ゆう＠管理人 | 2007-01-23 11:42
要素にクラスやidを指定している場合、
開始タグは（↓のように）明白なんですが、
<div class="section abstract">
終了タグは（↓のように）パッと見て分かりません。
</div>
どちらが要らないかというと、開始タグのコメントかなーと。どちらも無いなら無いでいいんですが。
投稿: kdmsnr | 2007-01-23 11:24