「レガシー」を保守したり、刷新したりするにあたり得られた知見・ノウハウ・苦労話 by Works Human IntelligenceAdvent Calendar 2024

初心者ほど読んでほしい、2年連続で大学祭のホームページを1から作り直した時の反省点と改善点

Last updated at 2024-12-27Posted at 2024-12-24

はじめに

私は過去2年間(本来は1年間、後述)に工大祭のホームページを担当していました。2年連続でホームページを1から作り直したのですが、最初からうまくやっていれば1回作り直すだけで済んだなと反省点も多かったです。この記事では過去の管理体制やコードの問題点、1年目に1人でリニューアルした時の反省点、2年目に担当者が変わってからリニューアルした時の反省点、今後の問題点について振り返りながら書いていこうと思います。

概要

この記事では以下のことに触れます

レガシーコードの問題点・防ぎ方
長年引き継がれても崩壊しない環境を作るために意識すること

技術的な話(変数名やスコープ、結合性の話など)はもっと参考になる記事がたくさんあるので、記事を参照して割愛します。この記事ではこれらを前提にした上で開発環境に関する話をメインで書いていきます。

こんな人に読んでほしい

何年も使い続けられるコードを書きたい人
担当者が良く変わる環境で開発をしている人(大学祭や学生団体のページ等)
開発経験が浅い人

結論

ここから長いですし、振り返りの備忘録感もあるので、特に興味が無い人に向けて先に結論だけ書いておきます。

レガシーなコード・環境を生み出さないためにも次のことにも意識しましょう。

ユーザーだけでなく開発者の環境も考えた開発をしよう

どんなにユーザー満足度が高くても～、どんなにデザインがよくアニメーションが豪華でも～、開発が苦痛に感じる環境ではより良いものは生まれない～

できるだけ多くの人の意見を参考にしよう

一人の視野と考えの狭さはやばすぎる。最初から他の人と相談しておけばな～ってこと、ありますよね?
相談も大事だしペアプロ、レビューも超大切。

技術選定はしっかりしよう

言語や技術の問題で作り直すなら最初からその言語でやれよと言われても文句は言えないです。技術選定の段階でも他の人や経験者の意見・知見を聞くことはとても大切です。

経験者と初心者の難易度の感じ方はかなり違う

経験者にとって簡単に見えるタスクでも、初心者には非常に難しく感じるかもしれない。できるだけコードは簡潔でわかりやすくしよう。ドキュメントやコメントも残そう。

時系列

開発背景です。読み飛ばしても問題ありません。

一人でリニューアルする (2022年12月～2023年11月)

工大祭のwebは(人手が足りないので)基本的に1人が担当します。第61回は自分が一人で担当して、第60回の前任の先輩にも意見・アドバイスや協力を得ながら開発をしていました。後で詳しいことは書きますが、60回までのレガシーコードは本当にひどかったです、ちいかわだけでなくはちわれも泣くレベル。そこで、過去のコードを使い続けるのではなく1から作り直して根本から解決することにしました。

担当者が変わる (2023年12月～2024年9月)

第61回が終わり、自分は大学祭実行委員会を卒業しました。そして62回では別の子が担当することになり、自分は引継ぎ・その後の開発の手助けをする形で関わりました。最初数回はよかったのですが途中から期限を過ぎてから作業を始める・不備や未完成が残ったまま公開することが増えてきました(レビューつけてもそのままマージされたり...)。途中から早めの期限を伝える等しましたが、結局自分が代わりに作業をする回数が増えてきました。最終的には~~クビになり~~自分が担当することになり、環境を整備するために数人友人を呼んで開発環境を整えることにしました。

チームで環境を整える (2024年9月～2024年11月)

前述の通りその年の担当者に代わり自分が担当することになりましたが、自分に戻ってきた時期から本祭まであまり時間が無いこと、他の人からのフィードバックや技術的アドバイスを貰うためにも開発経験のある友人を数人つれてチームで開発することになりました。1回目はデザインや使いやすさを重視していましたが、この時は開発環境を整えることを中心として、言語をNext.jsに変えたりCIを導入することで作業量・ミスを減らす環境を整えることを意識していました。デザインは61回に作成したものをほとんど使いまわしで、HTMLを切り取ってコンポーネントにしたりフレームワークを使って再現したりしました。

1人でリニューアルした時の話

前年までの問題点

前年の担当者とここがやばかったなってところを挙げました。
言語はHTML, CSS, JavaScriptです。(ところどころphpを使っていた形跡や拡張子もある)
もちろん過去の担当者も書きたくてこんなコードを生み出しているわけではないので悪しからず

コードの状態が劣悪
- インデントがバラバラ
- デッドコードもたくさん
- スタイルの指定方法がcssファイル以外にも<style>やstyle=""などバラバラ。どこで指定してるのか毎回確認が大変
- テンプレが無く前の年のをコピーしていたので、一回ミスが起きるとそれが毎年の標準になる。表示がおかしくなったらもう戻らない
- 画像の保存場所がバラバラ。同じ画像でも相対パス・絶対パスを使っているところがあり画像を移動すると大惨事
- リンクが絶対パス・相対パスバラバラ。移動したらリンク先がなくなる判定になることがたくさん。昔のサイトを見るとリンク先が無いものがいくつもある
- 命名規則もない。よくわからんクソコード(大体デッドコード)が散乱している。
- ページごとにスタイルや表示に例外が多すぎる。一般化できるところもバラバラのまま。結局その例外はデッドコードになる。
環境整備が未熟
- 引継ぎ資料はあるけど書いてないことも結構ある。前年の担当者が言わないとわからん。
- コードのドキュメントが無い?コード頑張って読もうね
- コメントアウトの説明は無い。コメントの無いクリーンで汚い環境
ZIPファイルで代々受け継ぐ。GitHub?バージョン管理?何それ状態
毎年変更箇所が多すぎる。開催年度やテーマ等全てのページで更新する必要がある。
デプロイが手動。ヒューマンエラーが起きやすい環境(自分も何回かミスった)

レガシーすぎる!!!このまま引き継いで作業をすると今後の担当者が全員苦労するだけなので、これを負の遺産として1から作り直すことにしました。
しかし、当時の自分もそこまで技術力・知識・経験があるわけでもなく、デザインを勉強していたこともあったので、見た目や使いやすさ等のユーザーの使いやすさをメインに改善し、言語や開発環境はそのままでした。

変更点

とりあえずデザインを改善し続けた
1年目はデザインの改善と使いやすさを意識しました。(開発経験も浅かったので改善点はたくさんあります)
前年までのページ: 第61回工大祭 2023
1年目に作成したページ: 第60回工大祭ホームページ
- トップ
  
  60回 61回
- 企画ページ
  
  60回 61回
画像のように、オレンジの線や枠を使ってスタイルを統一したり、画面内に表示される量を減らすことで全体像がすぐにわかるようにしました。(ちょっと過剰かもしれないけど)アニメーションも使うことで少し大学祭っぽくおしゃれにしました。
ページのテンプレを作成する
過去の問題として「テンプレが無く前の年のをコピーしていたので、一回ミスが起きるとそれが毎年の標準になる。」という問題があったので、ページテンプレートをコピーして作成することでミスが起きてもそのページのみに限定される、テンプレートを変えることで統一できるようにしました。
Gitを導入した
逆に今までよくできてたなと思うレベル。

反省点

開発環境よりもユーザー側を意識した開発だった

デザインや使い勝手を意識していたので、クラスの種類やページごとの例外が増えすぎていたり、divのインデントがかなり深いことになっていました。これではミスが多発してしまいます。Reactであればコンポーネント単位でわかりやすいのですが、HTMLだとクラス名から推測するしかないので、たまにdivが足りない等のミスが発生しました。

技術選定をしっかりするべきだった

リニューアルをするときに技術選定をせずそのままの言語、自分が知っている技術の範囲内で開発を始めました。結局これが原因で2年目にNext.jsに移行することになるのですが、当時はReactを知らなかったのでもう少し調べたりチャレンジするべきだったなとちょっと反省です。(開発していた当時はjsで要素を返す関数を作成して関数を呼び出して配置したりできないのかなと思っていましたがそれはまさしくReact, JSXの考え方ですね。)

他の人にフィードバックやアイデア、意見を貰いにいくべきだった

たった1人の視野と知識はとても狭いので、コードレビューを貰ったり技術に関して話し合う相手がいたらな～と思ったりもします。上で書いたReactを使ってたらなというのも1人でやっていたら技術力・知識不足で実現できなかった可能性は大いにありますが、経験者に相談していれば実現していただろうなと公開しています。
なにはともあれ、いろんな人の意見を参考にすることはとても大切です。

記法のミスが防げない、統一できない

stylelintやprettierを導入しなかったので、結局これではインデントやスペースを入れる入れないが人によってバラバラになってしまいます。当時はこれらの存在を知りませんでした。(調べるべきだった)

外見は良くなったと思ったら～中身はダメダメでした～、チクショー!!

担当者が変わってからの話

こんな感じで今思うと結局問題が山積みの状態で次の人に引き継ぐことになりました。一応テンプレートファイルの文字を書き換えるだけでページを作成することができるようになっていましたが、やっていくうちに以下のような問題も浮き彫りになってきました。

また、これらの問題に加えて、次の担当者の子が段々期限に間に合わなくなったり、レビューガン無視でミスをそのままマージしたり(プライベートレポジトリだったので、無料でprotect branchが使えなかった)で崩壊し始め、結局自分がやることが増えてきました。その後、そもそも工大祭自体にあまり注力していなかったのもあり途中で連絡が取れなくなってしまいました。

担当者が変わってからわかった反省点

開発環境を犠牲にしてユーザー側を完璧にするのはやめたほうがいい

ここまでに何度も出てきましたが、それだけ伝えたいです。例外ややることを増やしてまで見た目をよくするのはよくないです。困るのは今後担当する人です。ユーザー側だけでなく、開発環境も同様に改善して初めていい改善ができたと言えるでしょう。

ドキュメントの整備が追い付いていなかった

コード関連のドキュメントが追い付いていなかった、大反省。ドキュメントは書きましょう。

経験者の簡単は未経験からしたらとても難しいのかもしれない

ファイルをコピーしてテキストを変えるだけとはいっても初心者には難しいのかもしれない、変更箇所を見つけるだけでも困ってしまうだろうし。初心者からしたら修正不要とはいえ大量のコードを目の前にしたら、テキストを変更するだけでも不安になるのかもしれない。経験者からすると「調べたらわかるでしょ」と思ってしまうかもしれないが最初のころは調べ方もあいまいな人ももちろん多いですし。

求めるレベルが高すぎたのかも

大学祭は仕事と違い強制力は無いので、(他の人にどう思われるかは別として)別にやらなかったところで人生路頭に迷うわけではない。どれくらい重要だと思うかは人それぞれなわけで、ある程度やれば適当でいいや～と思われていたのかもしれない。

やらなくてもどうせ誰かがやってくれると思っていたのかもしれない

途中からミスは放置で公開することが増えていたので、結局自分が修正を入れたり、挙句の果てには納期を過ぎても仕事をしないことが増えてきて、その場合にも自分が代わりにやっていました。やらないとページを作ってほしい企画者に迷惑がかかってしまうが、やると当時の担当者からすると「やらなくてもどうせやってくれるしいいや」となってしまったのかもしれない。

担当者の子がわからなくても質問してくれない

その当時の担当者の子がわからないことに直面した時は即席で解決する or ミスのまま放置してレビュー依頼 or 無視の3択でした。聞きやすい環境は作っていたつもりでしたが、毎回期限ギリギリか少し過ぎてから作業を始めていたので聞きずらかったのかもしれません。わからないことはいつだって聞いてほしかったですね...

チームで環境を整えた時の話

これを受けて、急遽経験者の友人を数人読んで、色んな視点のフィードバックやアドバイスを受けながら開発環境を改善することにしました。
実際やってみて、複数人(全員経験者)で開発をすると開発スピードが尋常じゃなく早く、コードレビューや相談で良いコード・実装がどんどん出てくるのでやっていて非常に楽しかったです。なかなか経験者が集まることもないので、このチャンスにできる実装・改善はどんどん行いました。

変更点

デザインよりも開発環境の改善がメインです。デザインは61回のリニューアルで作成したものを若干改善し、HTMLで使いまわすところをコンポーネントにしたり、MUI等で再現しました。

言語をNext.js, TypeScript, CSSに移行
最終的に言語をHTML, CSS, JavaScriptからNext.js, TypeScript, CSS(css modules)に移行することにしました。
その時点の深刻な問題点として、同じ見た目でもページごとにコピペを繰り返す必要があるため作業量が多いことや配置やコピー箇所を間違えるミスが起きやすい等がありました。友人と技術選定を行った結果、
- コンポーネントベースで変更箇所が少ない
- 変数の値を変えるだけでページを跨いで関連する表示が変えることができる
- jsのコードを柔軟に使える
という理由でReactに移行することにしました。また、App Routerを使えばルーティングが楽なのでNext.jsを使うことにしました。
CIを導入して作業量とミスを減らす
手作業でミスが多かったデプロイは全て自動化しました。毎回mainに移動して更新する必要があるファイルを探してアップロードを待つ必要がなくなりました。また、CIを使ってテスト環境も作成し、公開前にスマホなどの実機で最終確認ができるようになりました。そのほかにもlintチェックも全てCIで自動化しました。
styelint, prettier, eslint等を導入
エラーの解消やインデント・文字数・スペース等が自動で統一されるようになりました
TypeScriptの型でミスを見逃さない
使いまわすデータは極力変数にして共有する
開催日時や回、企画データ等のいろいろなページで使いまわすデータに関しては極力変数でexportして使いまわすようにして一か所に集約し、変更が必要なものはわかりやすく、一括で変えられるようにすることで作業量とミスを減らしました。
ページごとに例外のあるコンポーネントを作成しない、共通の使い方で解決できる方法を考える
使い方やページによって結果が変わる、または似た名前で若干使い方が違うなどのコンポーネントは紛らわしくミスに繋がったり使われなくなったりするため、それらを使わなくても解決できる方法を模索しました。
コメントとPRをしっかり残す風潮を作る
全員でコンポーネントやpropsにコメントで使い方を書き記したり、PRをしっかりと書く習慣をつけるようにしました。今後の担当者もコメントとPRをしっかり書く風潮を残していきたいです。

実は、Qiitaのインターンの面接の際に「もしここから新しく実装するなら何をしたい?」(詳しく覚えてないけど大体こんな感じ)と聞かれたときに「Reactに作り直したい」と思い付きで答えてから「Reactにするの結構いいな、やっとけばよかった」とかなり後悔していました。個人的にはコンポーネントを展開したようなただただ作業量が多い負の遺産を作ってしまったのではないかと思うようになりました。が、このような形で実現できたのは非常にうれしかったです。
また、TypeScriptに移行することで型を使ってミスを減らすようにしました。例えば企画ページはobjectに企画データとしてkeyとvalueで作成したものを配置することで共通の形式で展開してくれるのですが、不足している情報がある場合はエラーとしてハイライトしてくれます。こういった使い方やシンプルに型のミス等を防ぐことができるので今後ミスを減らす・気が付きやすい環境になったかなと思います。

チームでリニューアルした時の反省点

経験者のチーム開発で環境を整えましたが、問題がなくなったかといえばそうでもないかもしれません。

レベルを引き上げすぎているのではないか?

Next.jsやCIを取り入れたが、そもそも論になってしまうが、大学祭のページはそんなに高度である必要があるのか?Next.jsやCIはそこそこ開発を経験してようやく触れるような技術なのに、もしかしたら初心者が担当するようなところでそんなものがあっても使い方がわからず活用できないのかもしれない。
しかもデザインや保守も完璧にしていると「自分がいじると壊したり悪化しそう」と思って新しいことが何もできなくなってしまうかもしれない。(他の大学祭のサイトを見ると簡易的なものやノーコードのもの、未経験ながらも頑張ったことがすごく伝わるページが多数存在する。)

TypeScriptで制限しすぎているのではないか?

ミスを減らすために型で固めているが、その分自由度も少なく、何か新しいことを実装しようと思ったら関数やコンポーネントを変更する必要がある。しかし初心者やChatGPTが変更を入れると崩壊してエラー祭りになったり保守できないことになってしまうかもしれない。そしてうまく編集するためにはある程度勉強する必要がある。果たしてそんなにガチガチに制限された開発は楽しいのだろうか。

根本としてWeb担当の体制の問題

一人で担当させるべきではない

人手が少ないので現状2人以上割り当てることができない状態です。しかし、一人でやると視野は狭くなりミスにも気が付きにくくなります。誰も見ていないのである程度適当にやってしまうこともできます。

担当者の冗長性が無い

担当者が辞めたか何かしらでいなくなった場合他に担当する人がいないので、他の人が代わりにやるかその年は無くすことになります。担当者がコロコロ変わったり前年の担当者がいないとなると情報や知識が継承されずミスや破壊が増えていくでしょう。もちろんそのためにドキュメントを残すのですが、ドキュメントだけでは限界があります。
また、担当者が「やっぱこの仕事自分に合ってないな」や「この言語自分に合わないな」と感じた場合でも1年間続ける必要があります。自分に合ってない開発程苦痛で楽しくないものは無いです。

Web開発をできる人が大学にそんなにいない

大学のCSの授業の中にWeb開発は含まれていません。大半の人はHTML, CSS, JavaScriptを書いたことが無いです。そのため、Web未経験の場合は独学でコードが書けるようになる必要があります。7~8割が大学院に行く中でWeb系に進む人は少ないため、開発経験としてはいい経験になりますが、将来使うのか?と考えた場合そんなにやる気が出ない人もいるかもしれません。

情報系でもプログラミングのレベルに大きな差がある

最近は特に情報系なのにプログラムを読み書きできない人が増えてきています。(ここでの読み書きできないとは、簡単な構文は前提で設計やリーダブルコード等を書いたり、既存のコードを調べながら理解できることです。)ChatGPTが普及してからは課題や開発でChatGPTを乱用する人が一定数おり、(使うことが悪いのではなく)出力されたものが理解できないけどそのまま採用する人がいます、今すぐ辞めた方がいい習慣ですね。動いてるからOK!!に繋がり、コードや環境が必要以上に変更されてコードが壊れたり見た目がバグったりしないか不安です。周りでもわからないコードを見たらとりあえずChatGPTに入れる、何かを実装しいならとりあえずChatGPTに言われた通りに実装してうまくいかない or なんかうまく動いてるけど何も身についていない人が少なくないです。できればもっとWeb開発の経験がある人や興味がある人に活用してほしいなと思います。

最後に

最初からベストなものを作ることは不可能に近いですが、改善の余地はたくさんあったかなと反省です。また、完璧なコードは存在しないし、全てのコードは文字通りレガシーになると個人的には考えています。担当者が変わればそれまでのコードは全てレガシーです。しかし、レガシーなコードにも使いやすいコード・改修しやすいコードは何年経っても消えることは無いのかなと思います。今後はそんなコード・環境を生み出していきたいです。

最後に、2年間もろもろ合わせて400時間程度工大祭の開発に尽力してきましたが、その中で得た経験はとても大きく貴重だったと思います。正直、もっと最短ルートを通れば同程度の開発経験は得られたかもしれませんが、レガシーコードを体現したことで得られた反省点は最短ルートでは気が付かなかったのかなと思います。
今後の担当者はこれを踏み台に今の環境で開発経験を積んでいってほしいですね。これ以上書くと「あぁ、工大祭現役だったあの頃に戻りたいな...」とおじさんみたいな感想しか出てこないのでこれで終わりにしたいと思います。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up

60回	61回