「ここから何についての記述かを示すコメント」の書き方を教えて下さい

Question

下記のようにコメントで、ここから特定のことに関する関数を記述するよと書いています。
このように目立つコメントを置くことで、ソースコードから目的の場所を探しやすくしているのですが、
やはりclassにまとめておくのが一番いいでしょうか？皆さんはこのようなコメントを書くことはありますか？

また、ページの章タイトルのようなものを記述する記法をご存知であれば教えて欲しいです。
JavaDocなどは決まった記述をするとドキュメントを生成してくれるので、そのようなもののために覚えておきたいです。

よろしくお願い致します。

例

##########
# csvの関数 #
##########

removeLastDelimiterOfCsv = (csvString) ->
  # 省略

concatWithCsv = (textElements) ->
  # 省略

createEmptyCsv = (columnNum) ->
  # 省略

#################
# localStorageの関数 #
#################

getRowFromLocalStorage = ->
  # 省略

Answer 1

自動生成を意識するのであれば、ドキュメントジェネレーターの流儀に従うのが一番でしょう。
CoffeeScript対応のドキュメントジェネレーターとしてはdoccoという物があるようです。
CoffeeScript本家のAPIドキュメント生成もこれを使っているようなので、
特にこだわりが無ければ、doccoを使うときの書き方をしてみるというのはいかがでしょうか？

Comments

[mitsuru793]

CoffeeScript本家がdoccoというジェネレータを使っているのですね。
教えていただきありがとうございます。

ドキュメントジェネレータを使用して、それに沿った形で記述するのが良いのですね。

Answer 2

関数をグループ化させる目的でクラスを用意するのはよろしくないですが、今回のような例ではクラスを用意したほうがいいと感じました。

# CSVを扱うクラス
class CSV

  # CSVのコンテンツを保持
  _content = ''
  
  # new CSV()で代用可
  create: ()->

  # Implement concat
  concat: (csv)->

  # Implement remove last delimiter
  removeLastDelimiter: ()->

# LocalStorageをラップして使いやすくしたクラス  
class LocalStorageAccessor
  # Implement get row from LocalStorage
  getRow: ()->

Comments

[mitsuru793]

関数をグループ化させることは良くないのですね。Utilクラスを作るのも良くないと見たことがあります。
クラスはCSVとLocalStorageのラッパーを別々にすればいいのですね。
ありがとうございます。