comments: why not what
TRANSCRIPT
![Page 1: Comments: Why not What](https://reader035.vdocuments.mx/reader035/viewer/2022062904/587a02841a28ab01268b4db7/html5/thumbnails/1.jpg)
Code Comments“Why”, not “What”
Sean Kelly@StabbyCutyou
![Page 2: Comments: Why not What](https://reader035.vdocuments.mx/reader035/viewer/2022062904/587a02841a28ab01268b4db7/html5/thumbnails/2.jpg)
About Me
Hi, I’m StabbyI’ve written code professionally for 13 years or something like thatI have super strong opinions about seemingly mundane topics
![Page 3: Comments: Why not What](https://reader035.vdocuments.mx/reader035/viewer/2022062904/587a02841a28ab01268b4db7/html5/thumbnails/3.jpg)
“Good code documents itself”
- A Filthy Liar, some point in time
![Page 4: Comments: Why not What](https://reader035.vdocuments.mx/reader035/viewer/2022062904/587a02841a28ab01268b4db7/html5/thumbnails/4.jpg)
Code CommentsA trip through history
![Page 5: Comments: Why not What](https://reader035.vdocuments.mx/reader035/viewer/2022062904/587a02841a28ab01268b4db7/html5/thumbnails/5.jpg)
Comments - ExamplesFortran
! This is a fortran commentLISP
(((((((((( ; This is a LISP commentCOBOL
* THIS IS A COBOL COMMENTC and most other languages (Go, for example!)
// This is a C or C-like comment/* This is a C or C-like block comment */
Python, Ruby, and some others# This is a Python or Ruby like comment
![Page 6: Comments: Why not What](https://reader035.vdocuments.mx/reader035/viewer/2022062904/587a02841a28ab01268b4db7/html5/thumbnails/6.jpg)
Cool things you can do with comments
You can make them carry hidden meaning for the compilerYou can use them to generate APIsYou can use them to build online documentationYou can use them to add metadata to generated codeYou can keep someone from MURDERING YOU by using them correctly
![Page 7: Comments: Why not What](https://reader035.vdocuments.mx/reader035/viewer/2022062904/587a02841a28ab01268b4db7/html5/thumbnails/7.jpg)
Go and CommentsGodoc is cool
But proper commenting is cooler
![Page 8: Comments: Why not What](https://reader035.vdocuments.mx/reader035/viewer/2022062904/587a02841a28ab01268b4db7/html5/thumbnails/8.jpg)
Comments in GoGo takes commenting very seriouslyLet the lint tools whine at you about missing commentsComments can be used to change build behaviorComing soon: There will be a standard comment for identifying generated filesGenerate perfectly acceptable online documentation
Including live examples!
![Page 9: Comments: Why not What](https://reader035.vdocuments.mx/reader035/viewer/2022062904/587a02841a28ab01268b4db7/html5/thumbnails/9.jpg)
Obligatory section about Godoc
Add the “godoc badge” to your reposDO NOT NEGLECT YOUR README.MD
Check out your local changes with the local godoc server: godoc -http=“:6060”Follow the suggested formatting style for commentsIn My Opinion(™): Godoc alone is NOT ENOUGH
![Page 10: Comments: Why not What](https://reader035.vdocuments.mx/reader035/viewer/2022062904/587a02841a28ab01268b4db7/html5/thumbnails/10.jpg)
Comments in GeneralComments require maintenance
They get out of date when code changes - fix themComments are not just there for you
Comments are there for other people who have to work on the code laterThey are also there for you in 2 weeks/days/minutes after you’ve forgotten everything you had in your head about the design
![Page 11: Comments: Why not What](https://reader035.vdocuments.mx/reader035/viewer/2022062904/587a02841a28ab01268b4db7/html5/thumbnails/11.jpg)
Comments in GeneralProviding examples in comments is useful, but don’t go crazy// TODO , // HACK, etc are perfectly acceptable, SO LONG AS YOU’RE TRACKING THEMYou always have time to write comments
![Page 12: Comments: Why not What](https://reader035.vdocuments.mx/reader035/viewer/2022062904/587a02841a28ab01268b4db7/html5/thumbnails/12.jpg)
WHAT
// SafetyValve is a threshold that we set to throttle the number of requests we make to the FooServiceSafetyValve = 80.0 // Only 80 concurrent requests at a time
![Page 13: Comments: Why not What](https://reader035.vdocuments.mx/reader035/viewer/2022062904/587a02841a28ab01268b4db7/html5/thumbnails/13.jpg)
WHY// We set this value so that we don’t overwhelm the FooService. Currently, it’s resource constrained and unable to handle exceedingly large request volumes, so we have upstream consumers provide a throttling mechanism. We eventually plan to replace it (lol)// After a series of tests, we’ve determined that roughly 80 concurrent requests at once per consumer will give us both the headroom we need to handle additional capacity by going wide with consumers during a large traffic spike, as well as provide an acceptable level of request queueing under those conditions without overwhelming any of the servers. Do not change this number without understanding and benchmarking what the ramifications will be.
![Page 14: Comments: Why not What](https://reader035.vdocuments.mx/reader035/viewer/2022062904/587a02841a28ab01268b4db7/html5/thumbnails/14.jpg)
“I can always figure out the what, if I look at the code long enough. But the context
of ‘why’ is lost forever unless written down”
–Me, right now
![Page 15: Comments: Why not What](https://reader035.vdocuments.mx/reader035/viewer/2022062904/587a02841a28ab01268b4db7/html5/thumbnails/15.jpg)
Thanks!“Why”, not “What”
Sean Kelly@StabbyCutyou