Code Comments“Why”, not “What”

Sean Kelly@StabbyCutyou

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

“Good code documents itself”

- A Filthy Liar, some point in time

Code CommentsA trip through history

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

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

Go and CommentsGodoc is cool

But proper commenting is cooler

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!

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

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

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

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

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.

“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

Thanks!“Why”, not “What”

Sean Kelly@StabbyCutyou