all right so to kick it off here we're
gonna do a vote I'm gonna show you two
pieces of code they do the same thing
and you're gonna decide which piece of
code does it in it expresses it in the
most clean way which piece of code is
the most clean we'll do it by a raise of
hands okay so look at it read it I'll
give you a minute
okay which piece of code is more clean a
raise your hand for a raise your hand
for B okay great
all right whoo which one is clean all
right read it which one's a okay now how
about B all right great we're about
50/50 for each one what what is what
does this block of code do you can go
ahead and just yell it out at me all
right we've got a user agent all right
cool
how many of you read by a show of hands
have heard this phrase you don't need
comments if you write clean code yeah
almost everybody so this is where I
think a lot of misconceptions lie in the
book the clean code by Robert C Martin
he talks about how comments shouldn't be
necessary because code should be self
documenting that if you feel a comment
is necessary
you should rewrite it to be more legible
I both agree and disagree with this in
the process of writing a comment you can
often find things that could be written
better but it's not an either/or I might
still be able to rewrite that comment to
be more self documenting and also write
a comment as well for the following
reason code can describe how but it
cannot explain why now this isn't a new
premise at all but it's a common theme
that I see in helpful comments that I've
come across the ability to communicate
something that code can
or can't precisely and all of that said
there's not just one way or right or
correct way to write a comment I believe
that our collective discourse about code
comments is far too shallow there are
good comments and there are bad comments
they can make our code bases more
legible and they can mislead us they can
guide us and they can be a crutch so for
that reason today we're going to be
talking about the art of code comments
I'm Sara Dresner I am a View korma
member of view I also am head of
developer experience at nella Phi which
is neither Netflix or Shopify as
confusing as it is for my parents it is
a really awesome way to deploy sites and
apps that I love that's why I asked them
if I could work there so I'm really
pleased to be to be with you all today
especially in Hawaii I'm sure we all I
appreciate the gap day yesterday that
was awesome
so I mentioned there's some nuance to
this there's good comments and there's
bad comments so we're gonna go over both
of them we're gonna start with the good
comments first what is the why many
examples of good comments can be housed
under this category code explains what
you'd like the computer to take action
on and you'll hear people talk about
declarative code where they're saying
rather than you know imperative code
where things are steps in a recipe
you're basically telling the computer
what you want it to do in the computer
does the heavy lifting well our comments
can also be more complete Clara t'v we
had to write this function because the
browser interprets everything is a box
this code doesn't describe what the code
below it will do it doesn't describe the
actions that we'll take if you found a
more elegant way of writing this you'd
feel confident that you could do you
could refactor it and because of this
less maintenance is required in order to
keep these comments around so if you
found a better way to write this you
probably wouldn't have to rewrite this
comment I think the funniest version of
this is from the former manager of react
course Sophie Alpert posted this this
comment is longer than the readme to
some of my repos the only piece of code
is that tiny little bit at the bottom
there
but this you know all of that
explanation was really necessary why
because it was a particularly nasty code
bit of code that and bug that she spent
a really long time debugging and so it
wasn't very straightforward and just
that one line of code doesn't express
all of the things that that one piece of
code does it can also clarify what's not
lit typically legible by humans
remember the user-agent thing that we
saw before that wasn't super legible
what about this does anybody know what
this does right this does anybody know
what this does probably not this targets
Firefox versions two to three this
targets Chrome Safari and opera I've
written code that needs something like
this and in order to avoid another
maintainer or future me assuming I took
some mushrooms on the way to work it's
great to tell people what the heck
that's for especially in preparation for
a time when you no longer need it maybe
they solve that browser issue or maybe
you're not supporting that browser
anymore and you can remove it who's
smart we are
who writes clean code we do it but you
don't have to look at you don't have to
comment look at how clear your code is
but think back to that first exercise we
did we weren't all on the same page
about what was clean the room was
divided at 50/50 on what was clean and
what wasn't people don't always agree on
these things and it's can be really
subjective and you can always assume
that what you're doing is the most clean
way of representing it but that even
changes over time
the code that I think is clean was clean
five years ago is not what I think is
clean today and you level up in
different ways another thing is that
we're all knowledgeable in different
ways if you're on a team where
everybody's skill set is more tightly
tightly knit you might have more
overlaps for what you think is clean you
might be more on the same page so maybe
this isn't as much of an issue but on a
team where the skill sets are more of a
Venn diagram you might not have the same
opinions might not have the same
background and that's okay it
look like I'm advocating for the smaller
skill set circle but look at how much
more ground this covers you have a
larger spread of expertise when you have
a team that looks like this or say you
get junior developers on your project on
bigger teams where you have a lot of
junior developers and engineers from all
types of backgrounds people might not
outright tell you that they need you to
comment but a lot of times they'll
express gratitude when you do comments
can be like chapters of a book if you
think of a book it's the same amount of
information whether you have paragraphs
or chapters or indexes but we split
those up why so that you can skim easier
so that you can pick things back up if
you've been out gone from time away and
that's true of our code - commenting or
section sections of code allows people
to get to the piece that's most relevant
to them but you might say we have
imports and modules and functional
programming absolutely that is awesome
and I'm so excited about that but
necessarily there's gonna be a time when
you get to a larger piece of code that
just has to exist sometimes commenting
different sections or making some
separation can help people find their
way more quickly a guide to keep the
logic straight while writing the code
sometimes I do this thing where if I
have a you know a big project where I'm
managing a ton of state from a bunch of
different things I'll write something
like this out get the request for the
server give us an error if it failed do
X thing with a request format the data
slit like so and so on and so forth just
making a long to-do list of little
sections so that I can break down my
tasks now these are weird one because
these aren't the kind of comments you
want to keep around if you keep them
around they can be misleading and we'll
get to that in a minute but they're
really helpful while you're writing the
code so you can break your tasks down
into smaller bits so in the process of
writing all of this code it can be
really helpful to write it like this but
then you should probably be remove it
because when left in your code as is
these comments can be a little screwy to
read later my perfect world suggestion
would be to use these comments at the
time of writing and then revisit them
after as you delete them you can ask
yourself does this do this
the most elegant way that I could is
there are not another comment that I
could write that might explain why this
is necessary what would I think is most
useful to express to another from
another mother this is okay Dora Factor
now this is an interesting one this
isn't this isn't my best work but we had
to get it in by the deadline how many of
you had have had a really aggressive
product deadline most of you okay maybe
you implemented a feature that you
yourself disagreed with and you were
like I don't know about this and there
are like oh don't worry it's an a/b test
or don't worry don't worry it's just
temporary and then it lived on forever
ever queue horror music as embarrassing
as it is to write a comment like this
sometimes it's super helpful as a
maintainer if I come across a comment
like this I'm not thinking like what's
wrong with this person how can I
sabotage their morning community I
I'm thinking okay I know that they were
probably under a lot of pressure and
it's okay for me to refactor I don't
even spend that much time thinking
through their process I'm all about like
alright let's get in the mode where I
can improve on this so that can be
really helpful for a maintainer I will
say don't use this as a crutch though
you can't just put this on every block
of code and call it a day right so but
it can be helpful to let other people
know what's going on commenting as a
teaching tool
are you a node shop that's been given a
client that's all Ruby
maybe it's totally standard Ruby but
everyone's in a little over their head
are you writing a tutorial for someone
these are limited examples when writing
out the how can actually be helpful the
person is literally learning on the spot
and might not be able to in just infer
something because they've never seen
that code before in their lives comment
that learning is humbling enough as
it is without them having to ask aloud
what you could they could more easily
infer on their own commenting doesn't
just have to be a teaching tool either
this this person did a really cool thing
where they held themselves accountable
for a tutorial by commenting
above every line of code exactly what it
was doing that's awesome he's holding
himself accountable for learning that
material line by line so it can be a way
for you to also you know keep yourself
accountable for what you're learning and
teaching as well I stack overflowed the
bejesus out of this did you just copy a
whole block of code from Stack Overflow
that's ok we've all been there something
that I've done that saved me in the past
is to put a link from where I got it
where I found it and so many times
people say to me but then I don't get
credit for writing that code and I would
tell them you're optimizing for the
wrong thing
inevitably people have different coding
styles and this is important because
what if you level up later what if
you're smarter later on and you revisit
this block of code and it's in a
completely different style than you're
used to and you actually know more you
might spend a lot of time sitting there
going wait why did I write it like this
when I know X is true another thing is
Stack Overflow is got a lot of traffic
you might go to that post later and find
out there's a better response that
happens all the time so this is a really
good way of for you to keep track of
those things as you move forward
comments can be really helpful April
Wenzel wrote this really awesome post
called it's time to retire RTFM and this
is why I think it's useful to add these
comments sometimes she makes a really
good point in this that in tech we get
comfortable with a sort of survivorship
bias and what I mean by that is well I
had to go through it so you have to go
through it too but the job of a senior
engineer the job of a more advanced
engineer is to make sure that the other
team can scale efficiently the job of a
senior engineer is to make sure that
everyone else can get going and be as
productive as humanly possible and
sometimes comments can help with that
and that means helping not letting
leaving people on their own if you know
the path all right let's say going into
the bad writing comments gets a bad rap
sometimes and that's because bad
comments exist so let's talk about some
ways
we can avoid doing this while writing
them they just saying what it's already
doing I think a lot of people get
frustrated because they see comments
like this stuff like this is a big pain
why because you're reading the same
thing twice in two different formats it
gives you no more information and in
fact it makes you process things twice
it's mental overhead rather than helpful
I've written comments like this but for
whatever the reason you have to take a
step back and be honest with yourself
and acknowledge that this comment isn't
helpful from a readers perspective it
wasn't well maintained bad documentation
can be worse than no documentation
there's no nothing more frustrating than
coming across a block of code where a
comment says something other than what
the code beneath it does and I think
that that really frustrates people and
they tend to get in the comments or bad
area but the comment is in your code
it's your job to work on it even if it
means deleting it so I think sometimes
people see comments and they're like
well that's optional that's not you know
I'm working on the code I don't really
have to you know mess around with the
comments here but the comment is
literally part of your code and you're
also trying not to you know mess up the
people who come after you so even if you
disagree with code comments and you see
a code comment just get rid of it if you
don't want to maintain it otherwise you
should be maintaining that along with
the code if you don't
it's worse than time-wasting it's
misleading it can lead people down the
wrong path if you write your code to be
good quality to begin with that express
the why and not the how you might find
that the maintenance issue actually goes
away so if we say we need to use the
flip technique to be more performant in
every browser if you switch it the code
from using get bound and client wrecked
to get Bbox which do similar but
different things because you didn't
write out the how you're not gonna have
to read rewrite everything you're
actually using the same thing because
that comment is expressing the why so
then you don't have to refactor the code
comments as well if you write really
clean code comments
orders but for code you changed
something you changed something you know
you like the new code but you just can't
quite get rid of that old code yet this
one's tricky because if you're not sure
if you're done yet it's okay to keep
these in because maybe you do need to
keep it in and use it again later but
hopefully hopefully you're all working
with version control and you're all
writing good commit messages so those
comments those pieces of code that
you're commenting should be retrievable
for you you should be able to look back
at the thing that you refactored and be
able to see what you refactored and
retrieve them if you don't and you move
away from the project in the future the
future you or your future teammates will
spend a few minutes trying to figure out
what went on here do we need this will
we need this it's time wasting to do
this to people trust your instincts and
your version control system get rid of
it you could have used a better name
I've done this before I've definitely
seen a lot of other people write code
like this before where the variable or
functions names are one letter and then
you comment what the thing is here in
the file this is a waste I know we all
hate typing but if you're using or a
variable or a function name repeatedly I
don't want to scan up the whole document
where you explained what the name did
where you could just use the name
precisely I can read this code now
previously I couldn't if I go back here
but if I look at this okay I know what
everything does right away that's much
more useful and much more legible and if
you're writing those comments to explain
what a name can do you're not naming
correctly I love this tweet by Mike care
I like the rule in functional
programming that if it's hard to name
perhaps you're giving the function too
much responsibility
refactoring has helped me name and
likewise trying to name has also made my
function smaller the comments are an
excuse for not writing the code better
to begin with and this is the crux of
the issue for a lot of people if you're
writing code that's half hazard and
you're
leaning on your comments to clarify this
means the comments are holding back your
programming this is a kind of horse
behind the cart scenario and
unfortunately even as the author it's
kind of hard to distinguish which is
which is which when you're really
getting going on a project we lie to
ourselves in myriad ways we spend time
writing a comment that could be better
spent making the code a little cleaner
to begin with we might also tell
ourselves we don't need to comment our
code because our code is so well written
even if other people don't agree just do
your best
there's not one true way when you're
writing comments it's not no comments or
yes comments it's thoughtful comments
that are good for the maintainer to read
try to envision that you're both the
author and the reader when you're
looking at that code when you're writing
your code you're both the person writing
it and the person maintaining it in the
future
what information do you need to be as
productive as possible
what would a younger you need it said
that 30% of time a developer's time is
spent writing code and 70% is spent
reading code my suggestion would be to
spend a moment after you think you're
done with a project and review with
commenting and legibility in mind and
I'll even submit PRS to myself when I
work alone I work alone on a lot of open
source projects I learned this from
Stacey Kivar in MO and it really helps
me look evaluate that code from a new
from new eyes I write it as the person
who's just trying to get this stuff done
and then when I submit the pr2 myself I
read it as a maintainer and someone who
has to maintain the code later I
encourage this practice more than one
thing can be true at a time people tend
to get on one side or the other of
whether or not you should write comments
but I would argue that the conversation
isn't really nuanced enough why not both
hopefully opening the floor to a deeper
conversation about this can help you
have write more meaningful comments and
it bridges the gap even so it can be a
lot to parse good anyways I'll leave you
with some better humor a while back
there was a Stack Overflow post where
people wrote the best comments that
they've ever seen and you can definitely
waste some time in here here's some here
some of them there
we're really good when I wrote this only
God and I understood what I was doing
now only God knows I dedicate all this
code all my work to my wife Darlene who
will have to support me in our three
children and the dog once it gets
released into the hover drunk fix later
burst of images are deleted by GDI plus
second dev I'm not sure about that some
dev one adding temporary tracking of
login screen five years later
[Laughter]
I'll leave you with this example that I
particularly like from Kelly Vaughan she
tweeted this out saying sometimes you
need to be your own cheerleader if you
can't read it it says this is not a
useful comment but you are useful and
you can do this that's true for all of
us - thank you so much
[Applause]