Catch Up: Go Style Guide Update

© 2025 ANDPAD All Rights Reserved. 1 Catch Up: Go
Style Guide Update Go Bash vol.2 #go_bash 小島夏海

© 2025 ANDPAD All Rights Reserved. 2 自己紹介小島夏海
(こじまなつみ) : replu : replu5 • 2021 年アンドパッド入社 • 登壇 ◦ Go Conference 2023: 「Go Style Guide」から学んだ可読性の高いコードの書き方 ◦ Go Conference mini 2023 Winter IN KYOTO: Go Getでのchecksum不一致に遭遇した話とその対応 ◦ Go Conference 2024: Mapのパフォーマンス向上のために検討されているSwissTableを理解する • 今年はLTでプロポーザル出して落ちました

© 2025 ANDPAD All Rights Reserved. ANDPADとは社内現場営業
/ 監督 / 設計事務 / 管理職職人 / 業者メーカー / 流通現場の効率化から経営改善まで一元管理できるクラウド型建設プロジェクト管理サービス案件管理資料工程表写真報告チャット黒板図面受発注 •　•　•     3

© 2025 ANDPAD All Rights Reserved. Go を間接的に使っているプロダクト ANDPAD の
Go のプロダクト Go がメインのプロダクト施工管理図面引合粗利管理検査黒板受発注ボード資料承認おうちノート … 4 歩掛管理請求管理入退場管理遠隔臨場

© 2025 ANDPAD All Rights Reserved. Go Style Guideとは •
2022/11/23 にGoogleから公開されたドキュメント [1] ◦ Go Style Guide と付属のドキュメントは読みやすく・慣用的なGoを書くための現在のベストアプローチを体系化したもの ◦ Goのプロジェクトによって支援されているわけではない ▪ 公式ドキュメントではない [1] https://google.github.io/styleguide/go/index 5

© 2025 ANDPAD All Rights Reserved. Go Style Guide？？？って人向け 6
• Go Style Guideって何？始めた聞いたなって人はぜひ一度読んでください。概要だけ知りたいって人はGo Conference 2023で自分が紹介しているのでそちらの資料みてください https://gocon.jp/2023/sessions/A4-S/

© 2025 ANDPAD All Rights Reserved. 更新内容を知りたい 10 Style Guideは
github.com/google/styleguide [1]で管理されている Goについては go/ ディレクトリの下にある [1] https://github.com/google/styleguide

© 2025 ANDPAD All Rights Reserved. go: Export the latest
version of internal guide. #801[1] 14 • Guide ◦ Line length • Decisions ◦ Import grouping ◦ Language -> Literal formatting -> Field names ◦ Language -> Function formatting ◦ Language -> Goroutine lifetimes ◦ Common Libraries -> Logging ◦ Useful test failures -> Assertion libraries ◦ Useful test failures -> Test error semantics ◦ Test structure -> Subtests -> Subtest names ◦ Test structure -> Table-drive tests • Best Practices ◦ Package size ◦ Error handling -> Error structure ◦ Error handling -> Adding information to errors ◦ Documentation -> Conventions -> Parameters and conﬁguration ◦ Documentation -> Conventions -> Context ◦ Documentation -> Conventions -> Concurrency ◦ Documentation -> Conventions -> Cleanup ◦ Documentation -> Conventions -> Errors ◦ Tests -> Use ﬁeld names in struct literals [1] https://github.com/google/styleguide/pull/801

version of internal guide. #840[1] 15 • Decisions ◦ Naming -> Initialisms ◦ Language -> Function formatting ◦ Language -> Don't panic ◦ Language -> Goroutine lifetimes • Best Practices ◦ Error handling -> When to panic ◦ Variable declarations -> Declaring variables with zero values [1] https://github.com/google/styleguide/pull/840

version of internal guide. #888[1] 16 • Decisions ◦ Naming -> Underscores ◦ Common libraries -> Contexts ◦ Test structure -> Table-driven tests • Best Practices ◦ Package size ◦ Imports -> Protocol Buﬀer Messages and Stubs [1] https://github.com/google/styleguide/pull/888

version of internal guide. #912[1] 17 • Decisions ◦ Naming -> Package names ◦ Test structure -> Subtests -> Subtest names • Best Practices ◦ Naming -> Test double and hepler packages ◦ Error handling -> When to panic [1] https://github.com/google/styleguide/pull/912

version of internal guide. #915[1] 18 • Decisions ◦ Naming -> Package names ◦ Imports -> Import renaming ◦ Useful test failures -> Assertion libraries [1] https://github.com/google/styleguide/pull/915

© 2025 ANDPAD All Rights Reserved. Decisions: Test structure ->
Subtests -> Subtest names 20 • スペースがアンダースコア、非表示文字はエスケープされる ◦ テストログとソースコード間の正確な対応関係を確保するためこれらの文字を使用しないことを推奨をという説明の追加 // Bad: t.Run("valid input", func(t *testing.T) { ... }) // Good: t.Run("valid_input2", func(t *testing.T) { ... }) --- PASS: TestSubtestNaming (0.00s) --- PASS: TestSubtestNaming/valid_input (0.00s) --- PASS: TestSubtestNaming/valid_input2 (0.00s)

Table-driven tests 21 • コード例の追加 • 説明の追加 ◦ 一部のテストケースが基本的なエラーチェックだけを必要とするような場合には、既存のテストにそのケースを追加することが許容される ▪ ただし、シンプルに始まったものが成長して保守不可能になる可能性はあるので注意は必要 ◦ テストヘルパーについて: テスト本体の可読性を維持するためにテスト設定を簡素化するのにも役立つ

Table-driven tests 22 func TestDivide(t *testing.T) { tests := []struct { dividend, divisor int want int wantErr bool }{ { dividend: 4, divisor: 2, want: 2 }, { dividend: 1, divisor: 0, wantErr: true }, } for _, test := range tests { got, err := Divide(test.dividend, test.divisor) if (err != nil) != test.wantErr { t.Errorf("Divide(%d, %d) error = %v, want error presence = %t", test.dividend, test.divisor, err, test.wantErr) } // In this example, we're only testing the value result when the tested function didn't fail. if err != nil { continue } if got != test.want { t.Errorf("Divide(%d, %d) = %d, want %d", test.dividend, test.divisor, got, test.want) } } }

© 2025 ANDPAD All Rights Reserved. Decisions: Naming -> Initialisms
23 • 表現の変更 ◦ before: 「IDはIdではなくID」 ◦ after:「英語の文書の一般的なルールに従う」 • 表の例もInitialism(頭文字)から English Usageになっている

© 2025 ANDPAD All Rights Reserved. Decisions: Naming -> Package
names 24 • 推奨しない名前として util 等と同じ並びで models 追加 • import時にリネームしたくなる誘惑に駆られる名前を避けるという説明が追加 • _testサフィックスについての例が追加 ◦ ブラックボックステスト(パッケージの公開APIのみをテストする場合) ▪ 命名規則: パッケージ名_test ▪ 例: linkedlist パッケージのテストは linkedlist_test ◦ 機能テスト・統合テスト ▪ 命名規則: アンダースコアと_testサフィックスを使用 ▪ 例: linked list サービスの統合テストは linked_list_service_test

© 2025 ANDPAD All Rights Reserved. Decisions: Imports -> Import
renaming 25 • 「同じパッケージには常に同じローカル名を使用して一貫性を保つ」の説明の追加 • protocol buﬀer packagesのリネームには pb サフィックスを必ずつけるようにとの説明の追加 • v1やutilのような無意味な名前をもつパッケージのリネームについての説明の変更 ◦ before ▪ リネーム推奨 ◦ after ▪ 控えめにリネーム可能 ▪ 周囲のコードから十分にコンテキストがわかる場合はリネームしない ▪ 可能ならパッケージ自体の名前をリファクタリングすることをおすすめ

© 2025 ANDPAD All Rights Reserved. Best Practices: Documentation ->
Conventions -> Errors 26 • 更新によって項目自体が追加されている • 関数が呼び出し元に返す重要なエラーについてドキュメント化し、呼び出し元が処理できる条件の種類を伝える • 関数が特定のエラータイプを返す場合、そのエラーがポインターレシーバかどうかをドキュメント化する ◦ 呼び出し元がエラーの比較にどの方法を取るか判断できるようにするため • 動作がパッケージ内のほとんどのエラーに当てはまる場合は、パッケージのドキュメントに全体的なエラー規則を記述する • 上記の例としてos pkgを示している

© 2025 ANDPAD All Rights Reserved. Best Practices: Imports ->
Protocol Buﬀer Messages and Stubs 27 • 項目名の変更 ◦ before: Protos and stubs ◦ after: Protocol Buﬀer Messages and Stubs • importのrenameで説明的な名前を推奨するように変更 // Bad: import ( pqpb "path/to/package/push_queue_service_go_proto" pb "path/to/package/push_queue_service_go_proto" ) // Good: import ( pushqueueservicepb "path/to/package/push_queue_service_go_proto" )

© 2025 ANDPAD All Rights Reserved. Best Practices: Package size
28 • パッケージを分割すべきかの判断基準の例が追加 ◦ 2つのパッケージを使うユーザーがどちらか一方を意味のある形で使うために両方のパッケージをインポートしなければならない場合、それらを1つにまとめるのが通常正しい選択 • non-canonical reference examples(非標準的な参照例)の追加 ◦ 小規模パッケージ: 1つのまとまったアイディア・これ以上何も加えたり取り除いたりしない ▪ csv/exvar ◦ 中規模パッケージ: 1つの大きなドメインをもち、それに対する複数の責務がまとめられている ▪ ﬂag ◦ 大規模パッケージ: 複数の密接に関連するドメインが複数のファイルに分割されている ▪ http/os • 参考文献の追加 ◦ Organizing Go Code (Blog Post)[1] ◦ Organizing Go Code (Presentation)[2] [1] https://go.dev/blog/organizing-go-code [2] https://go.dev/talks/2014/organizeio.slide

© 2025 ANDPAD All Rights Reserved. Best Practices: Error handling
-> When to panic 29 • 初期化関数で致命的なログを出力す代わりにpanicを呼び出すことが許了される ◦ 初期化関数として init だけでなく must function についての記載の追加 • panicをdeferする例が追加 ◦ この場合defer内で実行されるコードに関連するリソースに注意を払い必要がある ▪ close・free・unlock • 参考文献の追加 ◦ Handling panics[1] ◦ Run-time Panics[2] ◦ Defer, Panic, and Recover[3] ◦ On the uses and misuses of panics in Go[4] [1] https://go.dev/ref/spec#Handling_panics [2] https://go.dev/ref/spec#Run_time_panics [3] https://go.dev/blog/defer-panic-and-recover [4] https://eli.thegreenplace.net/2018/on-the-uses-and-misuses-of-panics-in-go/

© 2025 ANDPAD All Rights Reserved. Best Practices: Error handling
-> When to panic 30 type syntaxError struct { msg string } func parseInt(in string) int { n, err := strconv.Atoi(in) if err != nil { panic(&syntaxError{"not a valid integer"}) } } func Parse(in string) (_ *Node, err error) { defer func() { if p := recover(); p != nil { sErr, ok := p.(*syntaxError) if !ok { // Propagate the panic since it is outside our code's domain. panic(p) } err = fmt.Errorf("syntax error: %v", sErr.msg) } }() ... // Parse input calling parseInt internally to parse integers }

© 2025 ANDPAD All Rights Reserved. Best Practices: Variable declarations
-> Declaring variables with zero values 31 • 項目名の変更 ◦ before: before Non-pointer zero values ◦ after: Declaring variables with zero values • ポインタ型の変数の必要な場合にゼロ値を使用する例の追加 // Good: msg := new(pb.Bar) // or "&pb.Bar{}" if err := proto.Unmarshal(data, msg); err != nil {

© 2025 ANDPAD All Rights Reserved. Go Style Guide以外の情報元 •
Eﬀective Go[1] ◦ 公式のドキュメント ▪ 2009 年のGoのリリースに合わせて書かれており、それ以降大きく更新はされていない ◦ 網羅的に書かれているが、最新の情報はない ▪ 例えば context や generics についての記載はない [1] https://go.dev/doc/eﬀective_go 34

CodeReviewComments[1] と TestComments[2] ◦ 公式のドキュメント ▪ https://go.dev/wiki で管理されている ▪ 以前はGo言語のリポジトリのWiki内にあったが、wiki: move to x/wiki #61940[3] で移動した ◦ CodeReviewComments はレビュー中に寄せられた一般的なコメントがまとめられている ◦ TestComments はテストについてまとめられている ◦ 稀に更新されてそう ▪ CodeReviewCommentsは今年の5月にrand.Textについて更新されていた [1] https://go.dev/wiki/CodeReviewComments [2] https://go.dev/wiki/TestComments [3] https://github.com/golang/go/issues/61940 35

Uber Go Style Guide[1] ◦ Uber社が公開してくれているドキュメント ▪ Uber社内のガイドラインを文書化したもの ◦ 具体的なコード例が多め ◦ 頻繁ではないが更新されている [1] https://github.com/uber-go/guide/blob/master/style.md 36

Go standards and style guidelines[1] ◦ GitLab社が公開してくれているドキュメント ▪ プロジェクトの構造・依存関係管理・コードレビュー等についての記載やバージョン管理についてのルールなどコードのスタイルだけでなく、GitLab社の開発ルールについても公開されている ◦ コードそのものについてのルールはあまり多くなく、外部のドキュメントへのリンクが多数ある [1] https://docs.gitlab.com/development/go_guide/ 37

Thanos Coding Style Guide[1] ◦ Thanos Projectが公開してくれているドキュメント ◦ Eﬀective Go、CodeReviewCommentsを元にしている ◦ 信頼性とパフォーマンスに対しての関心が高そう [1] https://thanos.io/v0.13/coding-style-guide.md/ 38

Go (Golang) coding guidelines[1] ◦ Cockroach Labsが公開してくれているドキュメント ◦ User Go Style Guideを参考にしており、一部はEﬀective Go、 CodeReviewCommentsを元にしている ◦ エラーについての詳細なドキュメントがある [1] https://cockroachlabs.atlassian.net/wiki/spaces/CRDB/pages/181371303/Go+Golang+coding+guidelines 39

© 2025 ANDPAD All Rights Reserved. まとめ 40 • Go
Style Guideは不定期に更新されている ◦ 更新はgithub.com/google/styleguide[1] のgo/ディレクトリ配下を確認すればわかる ◦ Go言語の機能追加にそった内容以外にも説明が追加されたり、方針が変わっていたりすることがある • Go Style Guide以外にもいくつか参考になりそうなガイドが存在している [1] https://github.com/google/styleguide

Copyright © 2020 Present ANDPAD Inc. This information is confidential
and was prepared by ANDPAD Inc. for the use of our client. It is not to be relied on by and 3rd party. 無断転載・無断複製の禁止幸せを築く人を、幸せに。住まいをつくる。ビルや施設をつくる。街をつくる。生活を豊かにする建築・建設業は、幸せづくりと例えられます。私たちは、その幸せづくりをする人たちをテクノロジーの力で後押ししていきたい。心からそう考えてます。我々はこれからもお客様の声をサービスに反映して、建設業界及び建設業従事者様の業務効率化、 DX化を支援してまいります。 Mission We are hiring !! カジュアル面談応募フォーム開発部公式 X アカウント @andpad_dev エンジニア採用ページ

Catch Up: Go Style Guide Update

Catch Up: Go Style Guide Update

More Decks by ANDPAD inc

Other Decks in Programming

Featured

Transcript