Upgrade to Pro
— share decks privately, control downloads, hide ads and more …
Speaker Deck
Sign up for free
Menu
Search
Features
All features
Private URLs
Password Protection
Custom URLS
Scheduled publishing
Remove Branding
Restrict embedding
Deck Collections
Notes
Features
All features
Private URLs
Password Protection
Custom URLS
Scheduled publishing
Remove Branding
Restrict embedding
Deck Collections
Notes
Explore
Featured decks
Featured speakers
Programming
Technology
Storyboards
Explore
Featured decks
Featured speakers
Programming
Technology
Storyboards
Pricing
Search
Sign in
Sign up for free
Godoc: хороший, плохой, злой
Search
Ilya Kaznacheev
July 18, 2020
Programming
64
0
Share
Embed
Copy iframe code
Copy JS code
Copy link
Start on current slide
Godoc: хороший, плохой, злой
Ilya Kaznacheev
July 18, 2020
Transcript
43 slides
GODOC
Ilya Kaznacheev Remote Backend SWE Основатель Golang Voronezh Соавтор Z-Namespace
podcast Организатор конференций и митапов Любитель кофе
Golang Voronezh - ~30 активных участников - митапы - мероприятия
для новичков
- инструмент для встроенной в код документации - сайт для
хостинга документации публичных проектов godoc
documentation for a code
None
code v1.7.13 docs v1.1.6
documentation as a code
JavaDoc JSDoc Python Docstring ABAPDoc Godoc
what Godoc is?
Formatting guideline // ReadConfig reads configuration file and parses it
depending on tags in structure provided. // Then it reads and parses // // Example: // // type ConfigDatabase struct { // Port string `yaml:"port" env:"PORT" env-default:"5432"` // Host string `yaml:"host" env:"HOST" env-default:"localhost"` // Name string `yaml:"name" env:"NAME" env-default:"postgres"` // User string `yaml:"user" env:"USER" env-default:"user"` // Password string `yaml:"password" env:"PASSWORD"` // } // // var cfg ConfigDatabase // // err := cleanenv.ReadConfig("config.yml", &cfg) // if err != nil { // ... // } func ReadConfig(path string, cfg interface{}) error { … }
IDE support
IDE support
None
является ли Godoc идеальным инструментом для документации?
THE UGLY
None
None
THE BAD
None
None
THE GOOD
None
None
Документация может быть очень подробной, однако абсолютно бесполезной
как писать хорошую документацию?
не пишите книгу пишите инструкцию
от общего к частному
явная точка входа
реальные примеры и советы по использованию
примеры!
примеры! примеры!
примеры! примеры! примеры!
None
// ExampleGetDescription_customHeaderText builds a description text from structure tags with
custom header s func ExampleGetDescription_customHeaderText() { type config struct { One int64 `env:"ONE" env-description:"first parameter"` Two float64 `env:"TWO" env-description:"second parameter"` Three string `env:"THREE" env-description:"third parameter"` } var cfg config header := "Custom header text:" text, err := cleanenv.GetDescription(&cfg, &header) if err != nil { panic(err) } fmt.Println(text) //Output: Custom header text: // ONE int64 // first parameter // TWO float64 // second parameter // THREE string // third parameter }
None
✍
ведь есть README.md?
нет поддержки Markdown противно
у меня приватный репо, зачем мне вообще надо?
None
полезные ссылки dev.to/ilyakaznacheev/what-s-wrong-with-godoc-3319 blog.golang.org/godoc
ilyakaznacheev
More Decks by Ilya Kaznacheev
See All by Ilya Kaznacheev
Road to four nines
dreamworm
0
60
Many Layers of Availability
dreamworm
0
130
Stateful Solutions: A Hands-On Guide to FSM in Golang
dreamworm
0
230
CQRS
dreamworm
0
220
Building a Cloud-Native PaaS
dreamworm
0
200
Distributed System State Management: When Transactions Are Long and SLA Is High
dreamworm
0
190
How To Create Saga-Free Distributed Transactions
dreamworm
0
110
Architectural decisions in building distributed systems
dreamworm
0
60
Распределенные транзакции без саг
dreamworm
0
240
Other Decks in Programming
See All in Programming
flutter_test のその先へ — Flutter アプリの LLM 機能に「評価」という品質保証を
kosukesaigusa
0
200
Python Lambdaにおけるテストしやすい設計とAI支援の活用 / Designing Testable Python Lambda Functions with AI
kitano_yuichi
1
340
Apple Intelligenceとオンデバイス時代の到来
yahir0
0
250
Beyond Chatbots: Agentic UI with Open Standards @W-JAX 2026, München
manfredsteyer
PRO
0
120
SODA - FACT BOOK(JP)
sodainc
1
40k
baseline으로 마이그레이션, 리팩토링 안전하게 맡기기
fornewid
1
1k
例外からRich Errorsまで Kotlinエラーハンドリングの進化を読み解く
shiita0903
0
220
Rails初心者がパスキーを実装してみて大変だったこと
ktombow
0
220
[Kotlin Fest 2026] eBPF Tracing for Kotlin
takehaya
1
360
止まらない比較を止める — 余帰納法で無限ストリームを比べる
tarao
0
190
Growing PicoRuby's Ecosystem on ESP32
yuuu
2
150
LLM 101
dalinaum
0
510
Featured
See All Featured
Neural Spatial Audio Processing for Sound Field Analysis and Control
skoyamalab
0
620
Un-Boring Meetings
codingconduct
0
500
Balancing Empowerment & Direction
lara
6
1.4k
The browser strikes back
jonoalderson
0
2k
What's in a price? How to price your products and services
michaelherold
247
13k
Become a Pro
speakerdeck
PRO
31
6.4k
Building an army of robots
kneath
307
47k
How Software Deployment tools have changed in the past 20 years
geshan
3
35k
The Anti-SEO Checklist Checklist. Pubcon Cyber Week
ryanjones
0
310
Documentation Writing (for coders)
carmenintech
77
5.6k
The #1 spot is gone: here's how to win anyway
tamaranovitovic
4
1.2k
Impact Scores and Hybrid Strategies: The future of link building
tamaranovitovic
0
490