セクションコメントに何を使うか
コードの中にセクションコメントを仕込む場合、どんなフォーマットで書けばいいのかということを考える機会があった。
セクションコメントをどんなときに使うのか
一つのファイル内で意味がガラッと変わるセクションが混在することはまぁある。
例えば
import * as React from "react";
import styled from "styled-components";
type Props = {};
export const Component = (props: Props): React.ReactElement => {
return (
<Card>
<Head>head</Head>
<Body>body</Body>
</Card>
);
};
const Card = styled.div``;
const Head = styled.div``;
const Body = styled.div``;というのがあるときに、大きく
- import 文達
- props 型定義
- componnet
- styled component 達
にという文脈に分けられる。
この例はまだすっきりしているやつだが、これがおおきくなるととたんに見づらくなる。
これを整理するために、ここからここは props 型定義ですよーみたいに区分するときにセクションコメントを使う。
セクションコメントに求められることは
いろんなセクションが混在した場合に、あくまで人がコードを見るときの補助として用いられるのであって、ここがコンパイルされるということはなくていい。
つまり、あくまで
// シングルライン
/* ブロックコメント
または、マルチラインコメント*/を使って表現し、バンドルされる場合は排除されてほしいし、アプリケーションに影響があることはあってはならない。
OSS ではどのようなセクションコメントを使っているのか
eslint
//------------------------------------------------------------------------------
// Typedefs
//------------------------------------------------------------------------------react-select
// ==============================
// NO OP
// ==============================vue
見当たらない
apollo-client
見当たらない
react
見当たらない
material ui
見当たらない
stylelint
見当たらない
bootstrap
/**
* --------------------------------------------------------------------------
* Public Util Api
* --------------------------------------------------------------------------
*/JS、 TS における JSDoc annotation
JSDoc は記述した直後のコードに対して注釈をつけ、ドキュメントを生成することを目的としたジェネレーターである。
Use JSDoc: Getting Started with JSDoc 3
TS もこの JSDoc をサポートしている
TypeScript: Documentation - JSDoc Reference
/*
* 間に*が入るブロックコメントみたいな構文
*/この構文は直後のコードに対しての注釈なので、セクションコメントに向いていない。
例えば
import * as React from "react";
import styled from "styled-components";
/*
* styles
*/
const Card = styled.div``;
const Head = styled.div``;
const Body = styled.div``;と書けば、Cardに対して styles という情報が付くことになり不適切である。
結論
- これといったベストプラクティスはないので、プロジェクトで決めて統一すればいい
- JSDoc annotation を用いたセクションコメントは避けるべき