ククログ

WEB+DB PRESS Vol.86の特集記事「1年目から身につけたい！チーム開発6つの心得」を執筆しました

2015年4月23日発売予定のWEB+DB PRESS Vol.86の特集記事を、クリアコードとして執筆しました。社内の多くの人間が関わった力作となっております。書影はまだ登録されていないようですが、Amazon.co.jpでは既に注文できるようになっている模様です。

WEB+DB PRESS Vol.86
結城洋志/沖元謙治/足永拓郎/林健太郎/大竹智也/内田誠悟/伊藤直也/中山裕司/hiroki.o/泉水翔吾/佐藤太一/高橋俊幸/西尾泰和/舘野祐一/中島聡/橋本翔/はまちや2/竹原/麻植泰輔/WEB+DB PRESS編集部
技術評論社
￥ 1,598

この特集記事では、「1年目から身につけたい！チーム開発6つの心得」と題して以下の6つの話題を扱っています。

統一感のあるコード
見通しの良い設計
わかりやすい名前
伝わるコミット
コードを読む秘訣
情報共有のコツ

「新人開発者などの初級者向けに、リーダブルコードやコードリーダー育成支援に関連した記事を」という事でご相談をいただきましたので、当初は、弊社メンバーそれぞれが持っている「初級者に伝えたい話題」を持ち寄って、それをそのまま記事にするという事を考えていました。しかし、実際に挙げてみるとリーダブルコードなどの実装面の事以外の話題も多数出てきた上に、そもそも「よいコード」の必要性をまだ感じていないという段階の人に対して「こう書くとよいコードになりますよ」とだけ語っても心に響かないのではないかという疑問も生じました。そこで、「多人数のチームでの開発を円滑に進める上で、よいコードにはこのようなメリットがある」という切り口で話題を選定し、新人が先輩に教わって一人前のメンバーに成長していくというストーリー仕立てで、全体をまとめることにしました。

プログラムは何らかの処理をするための物であり、みんなで共同で制作した成果物そのものです。しかし、それと同時に、チームメンバー間での意思疎通の媒体にもなります。何時間もかけてコードの説明をしなくても、コード自体が読みやすい物になっていれば、コードを読むだけで、それを書いた他のメンバーが込めたメッセージを読み取ることができるでしょう。また、Gitなどのバージョン管理システムにおける個々のコミットやその履歴（コミットログ）も同様で、きちんと考えたコミットを積み重ねれば、それらもまたメンバー間でのコミュニケーションの媒体として活用できます。

個々のテクニックを身に着けることや、個人技としての技術そのものに囚われないで、何のために工夫をするのかという観点を持つことを、この特集記事では大切にして執筆しました。チーム全体の開発効率や成果物の品質などの全体的な底上げに繋がる知識として、実際の現場でも役立てていただけるはずです（弊社内でも実践しています）ので、チーム内での連携の取り方でお悩みの方はぜひご一読ください。

なお、ページ数の制限や話題の繋がりなどの都合から掲載には至らなかった話題は、ここ（ククログ）で記事として順次公開していく予定です。実際に、一部は既に「クリアなコード」カテゴリの記事として公開済みです。記事本編の補足になるような話題もありますので、本誌と併せてこちらもぜひご覧下さい。

この記事の続き

2015-04-08

リーダブルコードの伝え方

4月3日にschooで名著『リーダブルコード』を解説者と一緒に読み解こう ~7章制御フローを読みやすくする~というWeb授業をしました。資料と内容の概要は告知エントリーにあるので、興味のある方は参照してください。

授業の中で回答したもののうちよい回答をしたものがあったので紹介します。質問は「新人プログラマーにどうやってリーダブルコードについて伝えるか」です。授業の録画で言うと「Ｑ：リーダブルコードについては初日から教えますか？ 48:17」のところです。

みなさんは新人プログラマーにどうやってリーダブルコードについて伝えていますか？本を渡して「これ読むといいよ」ですか？「一緒にこの本を読もう」ですか？

回答は「自分がリーダブルコードを書くことによりリーダブルコードを伝える。本を読んでおけとも言わないし、そもそも『リーダブルコード』という用語も使わない。」でした。本を読んだり、「リーダブルコード」という用語があるという知識は、「リーダブルコードが当たり前」になってからで遅くありません。まずは、自分がリーダブルコードを書くことでリーダブルコードを伝え、リーダブルコードを当たり前にしてください。

実はこのことはリーダブルコードの解説にも書いています。より詳しいことは解説を読みなおしてみてください。

ちなみに、今回の授業は「受けたい数」が625人、「受講者数」は399人だったのですが、受講者のなかで「まだリーダブルコードを読んでいない」という人が8割ほどいました*1。おそらく、読んでいないけど「リーダブルコード」に興味があるという人が多いということです。このことから「リーダブルコード」という用語は普及していることがわかります。「リーダブルコード」の具体的な内容についてはまだ普及の余地がありそうです。

*1 正確に言うと、受講者のうち「リーダブルコードを読んだか」という質問に回答した人が29人で、そのうちの23人が「まだリーダブルコードを読んでいない」と回答しました。

この記事の続き

2016-01-06: 2016年にやりたいことと2015年のまとめ

2015-04-17

6月24日開催アジャイルアカデミー「実践リーダブルコード」募集開始のお知らせ

6/24(水)にアジャイルアカデミー「実践リーダブルコード」を開催することになりました。前回の3月6日に続いて、2回目の開催です。

「コードの読み手の視点」を身につける

「実践リーダブルコード」は、「リーダブルコードを書けるようになりたい人」や「リーダブルコードを書く開発チームにしたい人」が対象です。

ただし、このワークショップではリーダブルコードを書くためのテクニックは学びません。リーダブルコードを書くために必要な「コードの読み手の視点」を身につける事が、この講座の目標です。

リーダブルなコードかどうかはコードを読む側が判断するものですので、リーダブルなコードを書くためには、この「コードの読み手の視点」が不可欠です。この講座では「読む人が読みやすいならリーダブル」を合い言葉にして、今までとは違った角度からリーダブルコードへの理解を深めていきます。

「1年目から身につけたい！チーム開発6つの心得」にも関連

クリアコードでは、4/24発売WEB+DB PRESS Vol.86の特集記事「1年目から身につけたい！チーム開発6つの心得」を執筆しました。この記事は、チームによる開発をうまく回していくために不可欠な、「良いコードを書くこと」と「良いコミュニケーション」を実現するためのノウハウを紹介しています。

「実践リーダブルコード」で伝えたいことは、この記事に通じる内容です。「実践リーダブルコード」でも、「チーム開発6つ心得」で紹介するノウハウのいくつかを学ぶことができます。チーム開発6つの心得に取り組んでみようという方も、是非「実践リーダブルコード」の受講をご検討ください。

新人、ベテラン問わず学べる

実践リーダブルコードでは、開発チームでリーダブルコードを実践する方法として、「チームの『よい』を共有して、それを育てる」というやり方を学びます。これは「コーディング規約を作って守らせる」や「コードレビューで問題を指摘する」といったアプローチとは大きく異なりますので、開発経験豊富なベテランの方にとっても新鮮な学びになることでしょう。実際に、前回の受講者からもそのような声を多くいただきました。

まとめ

6/24に開催するアジャイルアカデミー「実践リーダブルコード」の募集を開始しましたので、講座の特徴を紹介しました。前回の内容はGitHubで公開していますので、ご検討の際は参考としてください。

ご興味をお持ちになられた方は、是非アジャイルアカデミーのページからお申し込みください。

2015-04-22

Markdownで書いたテキストをPDFに変換して納品用ドキュメントを作成する方法

色々なテキストを色々なフォーマットに変換できるPandocというツールがあります。今回は、これを使ってMarkdownで書いたテキストをPDFに変換する方法を説明します*1。

環境はDebian GNU/Linuxのsidを想定しています*2。

必要なパッケージをインストールします。非常に多くのパッケージをインストールするので時間がかかります。

$ sudo apt-get install -y texlive-full pandoc ruby rake

次のコマンドを実行して動作確認します。

$ pandoc -o test.pdf --latex-engine=lualatex test.md

そのままでは日本語を含むテキストをPDFに変換できないのでtest.mdには日本語を含まないようにします。これで日本語を含まないテキストをPDFに変換できることが確認できました。

日本語を含むテキストをPDFに変換するためにPandoc - TeX Wikiで紹介されている対策をします。

$ pandoc -o test-ja.pdf --latex-engine=lualatex test-ja.md

これで日本語を含むテキストをPDFに変換することができました。

Pandocで使えるMarkdownの記法についてはpandoc_markdown(5)やPandoc ユーザーズガイド日本語版を参照してください。

箇条書きや表組み等、一通り必要なものは揃っています。

体裁を整える

生成したPDFを納品用ドキュメントとするためには目次を付けたり、日付を入れたりして、体裁を整える必要があります。体裁を整えるためにはpandocコマンドにいくつかオプションを付ける必要があります。

以前、この方法でレポートを提出したプロジェクトでは以下のようなRakefileを使用しました。

require "rake/clean"

MD_FILES = FileList["*.md"]
PDF_FILES = MD_FILES.map{|file| file.ext(".pdf") }

task :default => :pdf

task :pdf => PDF_FILES

rule ".pdf" => ".md" do |t|
  sh "pandoc", "-f", "markdown+ignore_line_breaks", "-o", t.name,
     "--table-of-contents", "--toc-depth=3",
     "-V", "documentclass=myltjsarticle",
     "-V", "classoption=titlepage",
     "--latex-engine=lualatex", t.source
end

このRakefileでpandocコマンドに指定しているオプションは以下の通りです。

-f markdown+ignore_line_breaks: 読み込むファイルのフォーマットを指定します。ここでは入力がmarkdownであることと改行を無視するオプションを指定しています。
-o: 出力するファイル名を指定します。出力するファイルのフォーマットはファイル名から自動判別されます。なお、出力するファイルのフォーマットを明示的に指定したいときは-tオプションなどを使います。
--table-of-contents: 見出しから目次を生成します。
--toc-depth=3: 目次に出力する見出しのレベルを指定します。
-V documentclass=myltjsarticle: LaTeX用のオプションを指定します。このオプションでdocumentclassを明示します。
-V classoption=titlepage: LaTeX用のオプションを指定します。このオプションを指定すると表紙を生成します。
--latex-engine=lualatex: PDF生成のために使用するLaTeXエンジンを指定します。

オプションに指定可能な値を調べる方法

-Vオプションに指定可能な値を調べるには次のコマンドを使用します。

$ pandoc -D latex | lv

このコマンドで出力されるソースを読んで、利用可能なオプションを見つけて使います。利用可能なオプションを見つけるにはLaTexの知識が必要ですが、 $if(...)$ が使われているあたりを見ると、使われている値の名前がわかります。

メタ情報の書き方

以下のように、タイトル、著者、日付を表紙に入れることができます。

% Pandoc 調査報告書
% Taro Yamada <yamada@example.com>
% \today

# 概要

Pandocとは。。。

## 使い方

Pandocは以下のようにして使う。

# まとめ

以上よりPandocは。。。

YAMLフォーマットでメタデータを書く方法もあるようですが、手元では上手く動作させることができていません。

まとめ

Pandocを使ってMarkdownで書いたテキストをPDFに変換して納品用ドキュメントを生成する方法を紹介しました。

PDFの生成には少し時間がかかりますが、綺麗に出力できるので納品用のドキュメントをテキストエディタで書きたい人は検討してみてはいかがでしょうか。

*1 ククログはRD形式で書いているのですが、社内のテキストは少しずつにMarkdownに統一しています。

*2 Ubuntuでも同様の手順です。

この記事の続き

2015-04-27

AppVeyorへのGitHubプロジェクトの登録方法

AppVeyorというWindows用のCIサービスがあります。オープンソースプロジェクトは無料で利用できるので、GroongaとMroongaで利用しています。普段はGNU/Linux環境で開発しているため、Windows上でのビルドが壊れていないか確認できてとても助かっています。

AppVeyorはWebのUIから新しくCI対象のプロジェクトを登録できますが、ここではAPI経由での登録方法を紹介します。API経由での登録方法は次の2つのドキュメントを読むとわかります。

AppVeyorのドキュメントではPowerShellとC#を使ってAPIを使う例が紹介されていますが、ここではcurlコマンドを使う方法を紹介します。

手順

ここではpgroonga/pgroongaプロジェクトをAPIで追加することにします。手順は次の通りです。

APIトークンを確認する
リクエスト用のJSONを作る
リクエストを送る

APIトークンはAPI token - AppVeyorで確認できます。ここでは「xxxxxxxxxxxxxxxxxxxx」として説明をします。

リクエスト用のJSONは次のようにします。

{
  "repositoryProvider":"gitHub",
  "repositoryName":"pgroonga/pgroonga"
}

"repositoryName"の"pgroonga/pgroonga"は追加したいGitHubプロジェクトに変えてください。このファイルは/tmp/pgroonga.jsonに保存しているとして説明します。

これで準備ができたのでリクエストを送ります。ポイントは次の通りです。

APIトークンをHTTPヘッダーで指定する
Content-TypeHTTPヘッダーの値をapplication/jsonにする
HTTPメソッドはPOSTにする
APIのURLはhttps://ci.appveyor.com/api/projects

コマンドラインにすると次のようになります。

% curl \
    --header 'Authorization: Bearer xxxxxxxxxxxxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data-binary @/tmp/pgroonga.json \
    https://ci.appveyor.com/api/projects

成功すると次のようなレスポンスが返ってきます。

{
  "projectId": 114495,
  "accountId": 15636,
  "accountName": "groonga",
  "builds": [],
  "name": "pgroonga",
  "slug": "pgroonga",
  "repositoryType": "gitHub",
  "repositoryScm": "git",
  "repositoryName": "pgroonga/pgroonga",
  "isPrivate": false,
  "skipBranchesWithoutAppveyorYml": false,
  "enableSecureVariablesInPullRequests": false,
  "enableDeploymentInPullRequests": false,
  "rollingBuilds": false,
  "created": "2015-04-28T02:41:14.6822217+00:00"
}

失敗すると次のようなエラーメッセージが返ってきます。

{
  "message": "The request is invalid.",
  "modelState": {
    "request.RepositoryProvider": [
      "The RepositoryProvider field is required."
    ],
    "request.RepositoryName": [
      "The RepositoryName field is required."
    ]
  }
}