プログラミング内のコメントを英語、日本語両方の形式にする

[noborus]

重要度

中

問題点

プログラミング内<programlisting>内のコメントを翻訳する場合にCDATA内だとコメントが難しくなっています。
これをコメントアウトせずに日本語訳を追加したほうが読む側もありがたく、保守もしやすいと思います。
例：

コメントアウトするために原文の修正（^-行が発生）が必要。
ビルドすると日本語訳のみ表示される。

<programlisting><![CDATA[
--]]><!--
&#45;- instr functions that mimic Oracle's counterpart
&#45;- Syntax: instr(string1, string2 [, n [, m]])
&#45;- where [] denotes optional parameters.
--><![CDATA[
-- Oracleのものと同じ動作をするinstr関数
-- 構文: instr(string1, string2 [, n [, m]])
-- ただし、[]は省略可能なパラメータ
--]]><!--
&#45;- Search string1, beginning at the nth character, for the mth occurrence
&#45;- of string2.  If n is negative, search backwards, starting at the abs(n)'th
&#45;- character from the end of string1.
&#45;- If n is not passed, assume 1 (search starts at first character).
&#45;- If m is not passed, assume 1 (find first occurrence).
&#45;- Returns starting index of string2 in string1, or 0 if string2 is not found.
--><![CDATA[
-- string1内のn番目の文字から始めて、m番目のstring2を探します。
-- nが負の場合、string1の終わりからabs(n)番目の文字から始めて、逆方向に検索します。
-- nが渡されなかった場合は、1とみなします（最初の文字から探し始めます）。
-- mが渡されなかった場合は、1とみなします（最初に一致するものを見つけます）。
-- string1内のstring2の開始位置を、string2が見つからなければ0を返します。
--

コメントアウトせずに日本語訳を追加
ビルドしても表示は、ほほそのまま。

<programlisting><![CDATA[
--
-- instr functions that mimic Oracle's counterpart
-- Syntax: instr(string1, string2 [, n [, m]])
-- where [] denotes optional parameters.
--
-- Oracleのものと同じ動作をするinstr関数
-- 構文: instr(string1, string2 [, n [, m]])
-- ただし、[]は省略可能なパラメータ
--
-- Search string1, beginning at the nth character, for the mth occurrence
-- of string2.  If n is negative, search backwards, starting at the abs(n)'th
-- character from the end of string1.
-- If n is not passed, assume 1 (search starts at first character).
-- If m is not passed, assume 1 (find first occurrence).
-- Returns starting index of string2 in string1, or 0 if string2 is not found.
--
-- string1内のn番目の文字から始めて、m番目のstring2を探します。
-- nが負の場合、string1の終わりからabs(n)番目の文字から始めて、逆方向に検索します。
-- nが渡されなかった場合は、1とみなします（最初の文字から探し始めます）。
-- mが渡されなかった場合は、1とみなします（最初に一致するものを見つけます）。
-- string1内のstring2の開始位置を、string2が見つからなければ0を返します。
--

背景

バージョンアップ時にツールでCDATA内の置き換えをするのが複雑すぎるため

解決方法

No response

注意点

日本語コメントの前に「日本語翻訳」等のプレフィックスをつけるかどうか

貢献者として記載可否

以前の記載名を使用

貢献者名

No response

[KenichiroTanaka]

・運用も楽になる
・コメントも読みやすくなる（少々他のところと書き方が変わるけれども）
ですのでいただいている案が良いように思います。他にご意見ありますでしょうか？

[koizumistr]

読む側もありがたく、保守もしやすいと思います。

保守しやすそうとは思いますので、反対ではないのですが、出力がどんなふうに表示されるのかを実際にこの目で見ておきたい気も、、、

[noborus]

読む側もありがたく、保守もしやすいと思います。

保守しやすそうとは思いますので、反対ではないのですが、出力がどんなふうに表示されるのかを実際にこの目で見ておきたい気も、、、

割とそのままだと思います。

ビルドしたHTMLも置いておきます（しばらくしたら消すかもしれません）。
https://noborus.github.io/test/plpgsql-porting.html#PLPGSQL-PORTING-APPENDIX

[koizumistr]

ありがとうございます。

割とそのままだと思います。

ですね。
改めて見ると

日本語コメントの前に「日本語翻訳」等のプレフィックスをつけるかどうか

が確かに悩むところと思います。ないと一瞬？となりそうですし、かといって各コメントの先頭に毎回つくのもしつこいような気も、、、

[KenichiroTanaka]

多少しつこい感はありますが、それと、コメントのしやすさ/保守のしやすさとのトレードオフだと思います。
私はコメントのしやすさ/保守のしやすさを優先して良いのではないかと考えていますがどうでしょうか。

[koizumistr]

私の前の書き方だと誤解を招いているかもしれないので改めて。

「プログラミング内のコメントを英語、日本語両方の形式にする」には賛成です。（実際に結果も見てみて悪くないと思いました。）
『日本語コメントの前に「日本語翻訳」等のプレフィックスをつけるかどうか』については、どちらが良いという意見は持っていません。一長一短あると思います。「決まったらそれに従いましょう」以上のことは思ってないです。