This is a very quick talk about code comments. The aim is to make you aware of the importance of comments, but also to give you the impression that you should be commenting WHY something was done, not just WHAT

1. Code Comments
“Why”, not “What”
Sean Kelly
@StabbyCutyou

2. About Me
Hi, I’m Stabby
I’ve written code professionally for 13 years or
something like that
I have super strong opinions about seemingly
mundane topics

3. “Good code documents itself”
- A Filthy Liar, some point in time

4. Code Comments
A trip through history

5. Comments - Examples
Fortran
! This is a fortran comment
LISP
(((((((((( ; This is a LISP comment
COBOL
* THIS IS A COBOL COMMENT
C 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

6. Cool things you can do with
comments
You can make them carry hidden meaning for the
compiler
You can use them to generate APIs
You can use them to build online documentation
You can use them to add metadata to generated code
You can keep someone from MURDERING YOU by
using them correctly

7. Go and Comments
Godoc is cool
But proper commenting is cooler

8. Comments in Go
Go takes commenting very seriously
Let the lint tools whine at you about missing comments
Comments can be used to change build behavior
Coming soon: There will be a standard comment for
identifying generated files
Generate perfectly acceptable online documentation
Including live examples!

9. Obligatory section about Godoc
Add the “godoc badge” to your repos
DO NOT NEGLECT YOUR README.MD
Check out your local changes with the local godoc
server: godoc -http=“:6060”
Follow the suggested formatting style for comments
In My Opinion(™): Godoc alone is NOT ENOUGH

10. Comments in General
Comments require maintenance
They get out of date when code changes - fix them
Comments are not just there for you
Comments are there for other people who have to work on
the code later
They are also there for you in 2 weeks/days/minutes after
you’ve forgotten everything you had in your head about the
design

11. Comments in General
Providing examples in comments is useful,
but don’t go crazy
// TODO , // HACK, etc are perfectly
acceptable, SO LONG AS YOU’RE
TRACKING THEM
You always have time to write comments

12. WHAT
// SafetyValve is a threshold that we set to
throttle the number of requests we make to
the FooService
SafetyValve = 80.0 // Only 80 concurrent
requests at a time

13. 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.

14. “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

15. Thanks!
“Why”, not “What”
Sean Kelly
@StabbyCutyou