私の書いたFizzbuzzプログラムの改善点について

はじめに

私は実務経験なども無く、効果的な改善方法が思い浮かばないので、経験者の方々から改善点を伺いたいです。

実現したいこと

設計の適切さと使いやすさ、コードの見やすさ、ドキュメントの分かりやすさを改善したい。

リポジトリ

https://github.com/KazuyoshiHidaka/fizzbuzz

個人的に足りないと思っている部分

「自分が何も知らずにこの変数名を見たとしても理解しやすいか」、「自分が初めてこのドキュメントを見たとしたら見やすいか」。

自己評価

fizzbuzzプログラムを使う部分のコードが理解しやすいと思っている。

課題のリポジトリ内では、このようにfizzbuzzプログラムを外から使っています。

javascript
1fizzbuzz({
2  numStart: numStart,
3  numEnd: numEnd,
4  numFizz: numFizz,
5  numBuzz: numBuzz,
6  textOutputFizzbuzz: textOutputFizzbuzz,
7  textOutputFizz: textOutputFizz,
8  textOutputBuzz: textOutputBuzz,
9  textOutputElse: textOutputElse,
10  callbackCommon: ({num: num, textOutput: textOutput}) =>
11    appendTextElementToHTMLBody(textNewHTMLElement(num, textOutput)),
12});
13
14fizzbuzz();

純粋なfizzbuzzをしたい時は、fizzbuzz();のみで使えます。

自分では、変数名を分かりやすくしたつもりでいる。

それぞれの変数名の意味は、ドキュメントに記載しています。

ドキュメントが分かりにくいのではないか

今までドキュメントはあまり書いてこなかったので、分かりにくいと思います。
「このサンプル上でのfizzbuzzプログラムの扱い方」と「fizzbuzzプログラムの全般的な扱い方」について記載しています。

おわりに

「変数名の理解しやすさ」や「ドキュメントの見やすさ」を想像した結果が現状のリポジトリなので、経験者の方から指摘を頂き、改善したいと思い、teratailで質問させて頂きました。

ockeghem

2020/04/03 03:44

この問題やアドバイスは公開してもよいと言われているのでしょうか。

KazuyoshiHidaka

2020/04/03 03:53

コメントありがとうございます。言われていないので、内容を修正します。

yambejp

2020/04/03 04:04

徳丸先生につっこまれるとビビって言葉につまりそうですが初心者ってそういうところで躊躇しなくて済むのでいいですよねー

Zuishin

2020/04/03 04:18

- Fizz と Buzz と FizzBuzz の 3 つだけではなく任意の個数使えるようにした方が汎用的です。 - 剰余だけでなく boolean を返す任意の関数で判定する方が汎用的です。 - コールバックは外に出し、ユーザーが作れるようにした方が汎用的です。 - numStart や numEnd など関数内で定義されている値も外に出し、ユーザーが指定できるようにした方が汎用的です。 - numStart から始まり、numEnd までカウントアップするのではなく、任意の数列を使えるようにした方が汎用的です。 - 関数ではなくクラスで提供すれば、ポリモーフィズムの恩恵を受けることができるようになり、汎用性を保ちながらおすすめの設定を提供できます。

Zuishin

2020/04/03 04:35 編集

FizzBuzz のような単純極まりないアルゴリズムのものに読みやすいも何もないと思いますが、このコードは余計な if 文や余計なコールバックを多用しており、読みにくい部類に入ります。ドキュメントもとても読みにくく、読み進める気が起きません。中断しました。しかし表面上の読みやすさより問題なのは、設定がすべてハードコーディングされており、難読化されているだけで汎用性のかけらもないことです。仕様を満たしているか疑問です。

KazuyoshiHidaka

2020/04/03 04:35

ドキュメントの読みにくさは、「パッと見、もうダメ」って感じですか? 言われてみれば、パッと見、字が詰まってて読みにくいドキュメントになってますね。ドキュメントがきれいなリポジトリを参考に修正したいと思います。

Zuishin

2020/04/03 04:37

字が詰まるという問題ではなく、説明の必要ない舞台裏を延々と説明しているのが問題です。小説の冒頭で物語に直接関わらないエキストラキャラの説明が何ページも続いているような印象を受けました。

KazuyoshiHidaka

2020/04/03 04:44

小説の冒頭でエキストラキャラの説明が延々と続く感じでしたか。。リポジトリを立てた背景など、小説の冒頭に書いた方が良いですか?