Software Design 2022年1月号 第2特集(第1章、第2章)に寄稿【キッカケ、感想、書き足りない内容】

前書き:人生初!ソフト雑誌への寄稿 

技術評論社のSoftware Design 2022年1月号 第2特集(第1章、第2章)に寄稿させていただきました。

間違いなく、2021年で最も嬉しい出来事です!(エンジニア人生の中でトップクラスの嬉しさ)

     

「そろそろ技術同人誌でも書いてみようかなー」と考えていた矢先に、今回の寄稿に関する連絡が来て「素晴らしいタイミングだ」と感じた記憶があります。学生の頃から読んでいた雑誌に寄稿する事になるとは、世の中何が起こるか分からないものです。

              

寄稿のキッカケ

キッカケは、「Twitterで話題になった記事」と「本ブログ記事」が関連していた事です。

2021年の9月頃に「シェルスクリプトを書くのをやめる」という記事がTwitterで話題になりました。その流れで技術評論社さんが第2特集(Pythonで自動化スクリプト)を企画されたの事です。

企画の調査中に、本ブログの「Bash(Shell Script)からRubyやPythonに乗り換え!頻繁に使う処理を各言語で比較(2020年4月に書いた記事)」が目に留まり、寄稿依頼に繋がったとの事でした。

   

寄稿依頼のメールをいただいた後、「定期的にアウトプット(ブログの記事書き)を続けてて良かった」と感じたのは言うまでもなく。今年は本ブログの記事作成ペースが落ちていましたが、今後も技術ブログを継続しようと決意しました(ドメインとサーバーレンタル料を3年分、一気に払いました)

           

執筆スケジュールに対する感想

1ヶ月で21ページ執筆は、キツかった。

詳細な執筆スケジュールは別の方が詳細に記載されているので、そちらをご参照ください。ただし、私は認識合わせミーティングをしませんでしたし、「プロットが書けません。まずはザッと書き切らせてください」と発言するぐらい駄目な立ち回りをしました。技術評論社の担当者様は、不安だったのではないかと思います。

以下、記事執筆に関する日程(イベント)です。

記事執筆に関するイベント
  • 10/12:第1章 寄稿依頼 受領
  • 10/13:第2章 寄稿依頼 受領
  • 11/10:第1章 原稿提出(締切:11/15)
  • 11/15:第2章(サンプルコードなし) 原稿提出(締切:11/29)
  • 11/18:第2章(文字数削減かつサンプルコード付) 原稿提出(締切:11/29)
  • 11/24〜12/1:著者校正(複数回)、入稿版確認(1回)
  • 12/2  :作業完了

私の執筆スタイルは「土曜/日曜に2000〜3000文字を書いて、平日に300〜600文字を書く」という形であり、「完成していなくても原稿を月曜日に送付」していました。

「第1章/第2章(全16ページ≒19200文字)を1ヶ月で書ききれるか……」と不安を感じながら進めていましたが、最終的には「21ページからどうやっても減らせない」に変わりました。私は、仕事でも機能仕様書のページ数を予定より増やすタイプなので、このような結果になるのではないかと薄々感じていました。

個人的な感想(意見)ですが、1ヶ月で安全に書ききれるのは10〜12ページまで。今回は、運良く締切に間に合いました。仕事の業務量が増えたり、調査しなければならない項目が増えたら、1ヶ月で16ページを書くのはチョット厳しい。

                                

第1章:ファイル/ディレクトリ操作 執筆後の感想

第1章を書く前、心配事が2点ありました。

  1. シェルを悪者にしたくない(私はシェル派)
  2. Python APIの紹介記事を面白く書けるか

             

第1章については「古臭いシェルなんか止めて、キラキラPython使おうぜ!」と誤読されるのが嫌でしたし、「Python!? なぜRuby(Perl、etc)じゃ駄目なんだ!」という議論になるのも可能な限り避けたい気持ちがありました。そのため、言葉を選んで「Pythonは、こういう場合に使うと便利だよ」と主張したつもりです。

私はPythonよりシェルが好きです(≒使用頻度が高い)。BusyBoxもどきのOSS(未完成)を作るぐらいには、シェル(コマンド)に関心があります。ShellCheck(Haskell製のシェルスクリプト静的解析ツール)ShellSpec(シェル製のシェルスクリプトBDDスタイルテスティングフレームワーク)を活用して、可能な限りシェルでスクリプトを書けないかな、と考えたりもしています。

ただ、「開発チームで使う言語」という視点では、シェルは厳しさがあります(誌面中でも主張しました)。大前提として、シェルを用いた中〜大規模開発に関する文化は、2021年現在でも未成熟じゃないかなと考えています。例えば「関数が何を返すべきか(標準出力か返り値か)」「便利なシェルライブラリ」「プロジェクトディレクトリ構成」等に関する知見が少ない気がします。

正しい開発方法が分からない中で、チームメンバが手探りでオレオレスクリプトを作成します。すると、個性の強いシェルスクリプトやシェル芸を読み解く苦労が稀に発生します。ただただ辛い。そんな時にPython(Ruby、Perl …)を使えば!続きは誌面で

 

次に「Python APIの紹介記事を面白く書けるか」ですが、記事執筆中に迷いました。普通に考えると面白おかしく書けそうにありません。解決策として、なるべく比較する形式でAPIを紹介しました。過去バージョンとの比較、シェルとPythonとの比較、メソッド間での比較など。上手くハマったかは、不明(Twitterで恐る恐る感想を探します)

               

第2章:コマンドラインツール作成 執筆後の感想

正直に話せば、トピックの取捨選択を間違えたのではないかと不安に感じています。私が取り扱ったトピックは、起動時引数パース処理、ユーザ入力受付、ロギング、設定ファイル(TOML)です。

例えば、読者的には「パイプの受け取り方(下図)」「Pythonパッケージ構成」あたりの方が嬉しいトピックだったのではないかと、原稿提出後に考えたりしました。あと2ページあれば、追記できたのに……(限界までページ数を増やしていたので、追記の申し出は流石にしませんでした)

      

さらに言えば、ロギングは大事な部分をページ数の都合で、泣く泣くカットしています。以下、カットした内容です。「出力されないログは意味がないよね」とか、色々と書きたい内容がありましたが、必要最低限の内容のみが誌面に登場しています。

ロギングの難点

 ロギングで迷うのは、「どのタイミングでどのログレベルを用いるべきか」および「何を出力すべきか」ではないでしょうか。どちらも、開発対象プログラムやチームによって見解が異なります。

 ログレベルの使い分けでは、チーム内で「コードレベルのロギングサンプル(実装例)」や「各ログレベルと出力内容の対応表」等を用意し、ログレベルに対する共通認識を持つとベターです。ベストは、ロギングの設計書をキチンと作成する事です。少なくとも、ログレベルを使い分けないのは重要なログを探すのに時間がかかるため、避けるべきです。

 ログ出力内容としては、少なくともバグ原因が特定できる情報が必要です。例えば、ログ出力時刻、処理開始前の変数状態、処理中の状態(現在の処理件数や異常発生の有無など)、処理終了結果、エラー発生箇所を特定する情報(異常/例外発生時のエラー種類)等が考えられます。逆に、出力すべきではない内容もあります。例えば、個人情報や顧客機密、パスワード、セッションID等をそのまま出力するのは避けましょう。

原稿提出が12月であれば、log4jの脆弱性問題についても触れた気がします。log4jはJavaロギングライブラリであり、任意コード実行できるバグが埋め込まれていました。このバグはセキュリティ脆弱性の深刻さを表すCVSSスコアがほぼMAX値かつ、よりによって金曜日に存在が知れ渡るという最悪の代物。休日返上になったJava開発者が少なからずいる気がします。

個人的には上記の問題を眺めていてOSS開発とお金の関係が気になったので、その点について記事を書いたりしました。

「Log4j2の脆弱性から垣間見えたOSS開発の厳しさ」と「OSS開発者に投げ銭する文化(未来)」について

               

最後に

少しでも多くの知識が読者の皆様に伝わるように記事を執筆したです。読者の皆様に楽しんで読んでいただければ、私は嬉しいです(どんな感想があるか、ビクビクしていますが)

また、技術評論社 担当者様には何度もワガママを聞いていただき、最終的にはページ数やレイアウトを私が納得行く形に調整していただきました。

この場を借りて、お礼を申し上げます。1ヶ月以上の期間、ありがとうございました。

 

 

おすすめ

2件のフィードバック

  1. 2022年5月15日

    […] 前回のSoftware Design 2022年1月号は、本技術ブログ経由で寄稿依頼をいただきました。 […]

  2. 2022年6月4日

    […] Designに記事を2回寄稿したり(寄稿感想その1、その2)、LPIC […]