
Every line of code is always documented - jessaustin
http://mislav.uniqpath.com/2014/02/hidden-documentation/
======
RyanZAG
You really shouldn't have to be relying on history for all of that context. It
should definitely have been a function simply called 'triggerLayout()'. Then
the exact and best method for triggering layout could be put in that function
and used throughout the project where necessary, and easily updated if a
better method of triggering layout comes along.

Code like this is extremely brittle with or without that git history, don't
rely on it like a crutch as it makes the code obscure, and updating a line
somewhere may leave other similar lines updated or not. If you wanted to
update the triggerLayout function, you would have to go through the git commit
log for every .clientLeft line to see if that one was or wasn't used for
triggering layout...

~~~
etler
"Code happens". In reality, there's code that should have been commented all
the time and even in the best codebases. I don't think there's a coder in the
world who hasn't had a time when he's looked back on a piece of code and just
thought "what?". If you get in the habit of keeping a well documented git
history, it's an invaluable resource. I find on top of these benefits, having
to explain what changes I made also helps me make smaller and easier to
understand commits, which also helps with summarizing releases, finding
commits where bugs were fixed or introduced, and so much more. A well
documented git history is the closest thing to a time machine you can get.

Should these things happen? No. Do they happen? All the freaking time.

~~~
RyanZAG
What? No, it's got nothing to do with commenting. It's to do with basic code
design: put your stuff in functions. A line like that should have been in a
function to start with, and it should have been caught during a code review or
as common sense by the committer before he even committed.

~~~
aidos
Agreed. Maybe it's in some insane tight loop where you don't want a function
call - in which case you comment it. My rule is that if there's something I
have to put in the code that's out of the ordinary, I comment to explain.

------
jakejake
This is probably not a popular view, but I don't really understand why
comments are viewed by some people as a bad thing. I agree that useless,
redundant comments are not helpful. But that doesn't mean all comments are
useless. I don't agree that well-written code never needs comments either.
Reading the code tells you _what_ it does. It doesn't always tell you _why_
it's there.

Digging through version control comments seems to me a last-ditch effort to
figure out what some code is doing. If the project had any significant history
you could be digging through hundreds of commit messages. Why not just put a
1-liner comment above that line and save every subsequent developer the hassle
of wondering what the heck that seemingly useless line does..?

~~~
geoka9
> This is probably not a popular view, but I don't really understand why
> comments are viewed by some people as a bad thing.

Probably the same people think that well-written code does not need comments
at all. That may be so, but well-written code is hard to come by. While this
rock-star macho attitude is aplenty.

~~~
ghayes
And to be perfectly honest, well written code might not stay well written as
project circumstances change. Thus, documentation that can be updated often
makes life easier going forward.

~~~
tetha
And even worse, sometimes code can't be well-written once you start
interfacing with third party software with quirky shenanigans. We got quite
some comments flying around such as "In case you are wondering: yes, this call
is necessary, or this and that situation will propagate through these two
libraries and break with this obscure, unhelpful error message. If you ever
change this, look at those documentation files for unobvious, scary testcases
to look at".

------
crazygringo
But why would you only comment this in the git history?

Why on earth wouldn't you place this explanation _in a comment preceding the
line of code itself_?

One of the best things I ever learned in programming is that you shouldn't
write code to be executed -- you should write code to be read and understood
by _other people_.

It's going to take me forever to read your file and understand what's going on
if I have to do a git blame on every other line.

Just use short _purpose-based_ commit messages (fixes a bug where..., so
now...), and then put the actual _why_ behind the implementation in the source
code comments itself!

~~~
j-kidd
In my opinion, the full explanation is too long to be put as code comment, but
is just right as the commit message. The best way is to keep the commit
message, but add a short comment like:

    
    
        // Hack to trigger layout change in latest Mozilla
    

Then, whoever interested in the hack can read the full explanation from the
commit message.

Basically, for simple code with unclear purpose, I'd go with short comment in
the code plus full explanation in the commit message. For hard-to-read code
with complicated logic, I'd go with long comment in the code. Or refactoring.

Ticket description, commit message, code comment, and the code itself are all
necessary to keep the codebase "documented".

~~~
crazygringo
I'm genuinely curious -- what is the thinking behind "too long to be put as
code comment"? I've never heard that before.

It's not like we're conserving paper. And syntax highlighters helpfully give
comments different colors so you can skip over them while reading.

Personally, I've never once wished that a particular piece of code were _less_
commented, but there are hundreds if not thousands of times I've wished that
there was _more_ explanation, or any at all.

~~~
einhverfr
Long comments get out of date quickly because it isn't clear how the comments
relate to the code on a quick scan. In this case, you want a quick note as to
why the code is there. You can add external references if needed.

You don't want to make someone who is editing code stop to think about how it
affects the comments.

~~~
tsiki
>You don't want to make someone who is editing code stop to think about how it
affects the comments.

What's the point of comments then if your general rule is that it should be
fine to edit code without changing the comments?

~~~
einhverfr
> What's the point of comments then if your general rule is that it should be
> fine to edit code without changing the comments?

Not without changing the comments. Without stopping to ponder how two
paragraphs of comments fit into the code changes. The comments (aside from API
documentation) should annotate the code, not the other way around.

------
shaggyfrog
It sounds like "this.get(0).clientLeft" should have been a single-line
function named something like
triggerLayoutInMozillaAndFirefoxToFixAnimateForNewDomElement, or if you don't
like massive function names, a comment that says that.

Spelunking through commit history shouldn't be necessary learn the intentions
behind those kinds of actions.

~~~
etler
It doesn't matter if it should have been commented or not. The reality is it
wasn't. If you get in the habit of explaining your changes in git messages,
every line change will have documentation, or at least an owner so you can ask
them about it.

If you do need to go git spelunking to figure out what's going on, you'd have
to be insane to not add a comment afterwards.

Either way, "shoulda coulda woulda". If the code doesn't have a comment, it
doesn't have a comment. These things happen, and you can't change the past.
But with git, you can relive it.

~~~
jkrems
Reality could also have been: the commit message wasn't as helpful. Or the
message would have been but the file was moved, copied, the indentation level
changed, or any number of things that destroys the connection to the original
comment. The article sounds like it advocated treating the commit message as
the primary means of documentation - which is hardly a good practice.
Meaningful identifiers/function names, and comments for non-obvious code
should come first. If someone prioritizes elaborate commit messages and a
clean history _before_ good code, the techniques outlined in the article might
be useful, for sure. But it says: "A project’s history is its most valuable
documentation." \- which is, frankly, not true for most projects. And if it is
true, it's a bug, not a feature.

~~~
etler
I did not interpret the article as being git should be a primary source of
documentation at all. I have a hard time seeing which part of the article
implies that. I think he's just pointing out how it's another tool you can
use.

~~~
jpatte
From the article:

 _A project’s history is its most valuable documentation._ (...) _The quality
of this documentation, however, relies heavily on the diligence of the people
involved while writing commit messages._

Requiring such diligence when writing commit messages, while at the same time
allowing the same people to write opaque code as shown in the example, would
be absurd.

------
zmmmmm
This would only seem to work for relatively fine grained commits or projects
in maintenance mode.

Apart from that, to rigorously apply it would break the author's own advice or
common sense source control practise - suppose I make 4 changes in separate
files to fix a bug. Do I check them in separately so that I can put my pseudo
code comments into the revision history? Now I have broken the atomicity of my
revision history. If I check them in all together do I type a whole essay into
the revision history about why each change was made in each file? It'll
quickly all fall apart.

It also relies on the reader _recognizing_ that they need to be curious about
the code here. What it if didn't look so curious? It could easily get cleaned
up or modified without a comment to alert the reader.

For people and projects in specific contexts it can work but there are plenty
of situations where this is a terrible idea.

~~~
mattdawson
Totally agree with the "might me good for maintenance mode" sentiment. I'm
working on a pre-1.0 project. I'm thinking about the few commits where I was
first implementing localStorage caching. Tons of files were effected on each
commit. If there was a particularly tricky line in there (there were several),
how would I have specified it in a commit? That'd be extremely hard to read
when compared to the alternative of _putting the comment above the code_.

------
markm208
I agree with the author that historical information about how a codebase has
evolved is important. I would also argue that code comments are not always the
best place for this historical information (if you don’t know about the deep
past of a bit of code, then why would you want to see a code comment
describing some change to it?).

I suggest we take a step back and ask if modern version control is the best
way to store historical information. Modern version control systems (git,
mercurial, etc.) were built within the last decade or so but they were built
with the same constraints as the original version control systems of the
1980’s. They are optimized to be disk efficient (and don’t get me started
about their command line interfaces). This is crazy!

We should store much more about the programming process than the data gathered
if and when a developer chooses to commit. We should record it all- every
keystroke. No human generated source of data is ever going to fill up our hard
drives or the cloud. Don’t optimize for the disk!

This data can be used to replay programming sessions so that others can learn
exactly how the code evolved. Developers could then comment on the evolution
of their code. Think of this as a modern commit message. I am working on a
project that attempts to do this:

[http://www.storytellersoftware.com](http://www.storytellersoftware.com)

~~~
icebraining
I don't see it as optimizing for disk, I see it as optimizing for time, by
presenting relevant events vis-à-vis showing every irrelevant detail. Much
like a movie or novel doesn't usually show its characters going to the
bathroom, neither should my coworkers have to sift through my misspellings,
dumb decisions and irrelevant debugging.

I agree that we could benefit from saving more (e.g. relevant exploratory
sessions, though those tend to happen in the REPL, not in the code editor),
but I disagree with an indiscriminate approach.

~~~
dkuntz2
Storyteller has ways to filter out your misspellings, dumb decisions, and
irrelevant debugging.

While the process for filtering out dumb decisions and irrelevant debugging is
a little convoluted at present, filtering out misspellings is really easy if
they're made within X seconds (where X is defined by you). Because Storyteller
currently only supports IDEs (specifically Eclipse, hopefully with support for
Visual Studio soon) you should be able to notice those quickly.

As for processing out dumb decisions, you don't really know they're dumb until
after you've made them, and someone new to a part of the project might also
have the same idea you had when made those decisions, and seeing that you made
them, hopefully coupled with some comments on what went wrong with those
choices could push them in a different direction, or help them fill in a piece
you were missing. Watching those past decisions could also help you in the
future when you come back to some code and can't remember what you did before
or why.

Exploratory sessions only happen in REPLs when the language has a REPL.
Considering that Storyteller's written in Java, has support only for an IDE
that was initially built for Java, and has been written by a bunch of college
students and one professor at a college where most CS courses use C++ or Java,
REPLs aren't really things most of us use (I want to change that, but there's
only so much you can do through an extracurricular organization).

Plus, we're developers. Why store only some data when you can store _ALL THE
DATA_!

------
meistro
> var one = "foo"
    
    
      , two = "bar"
    
      , three = "baz"
    

Agree with the author that this is easier to change, and in JS it will keep
you from accidentally leaving a trailing comma. That being said, I find it to
be very unreadable(which is where most your time will be spent) and most text
editors/IDE's make it a burden to work with.

~~~
sonnym
While I agree with making code editable in single lines as much as possible, I
think this is a particularly bad example. I do prefer the comma first style
for arrays and objects, but not for variable declarations. I used to use this
exact style a couple years ago, but now I prefer to explicitly declare every
variable with `var` to prevent any possible, syntactically correct, error that
would result in a global variable.

------
gtirloni
Checking the history is much slower than a comment right there in the code.
Repeat this a thousand times and you've lost precious time hunting for
information.

------
rymohr
Great article! Mislav definitely knows his git.

What he didn't point out though is that he was actually the one that
contributed that code in the first place.

[https://github.com/madrobby/zepto/pull/586](https://github.com/madrobby/zepto/pull/586)

[https://github.com/madrobby/zepto/commit/3d92f20966aa02dee82...](https://github.com/madrobby/zepto/commit/3d92f20966aa02dee8249daaefc5f8b6623e00de)

As others have commented, long explanations like this have no place in commit
messages. Comments should always be used to explain what you're doing and why
you're doing it. Commit messages should simply summarize what you did.

A better commit message would have simply been:

fix animate() for elements just added to DOM

See included comments for explanation.

------
zimbatm
It's a good example of a place where a comment should have been added. The
user got lucky because the line's last commit happens to contain the
meaningful explanation. He could also have stumbled along a formatting change,
variable name change, file rename. The spelunking becomes harder than just
reading the comment that could have been on top of that line.

------
jasonkester
Here's me doing the HN thing and analyzing the code sample rather than the
article itself. Sorry in advance.

But if you're going to do this trick and you use a code compiler of any sort,
you'll need to assign the value of that clientLeft somewhere. Otherwise your
compiler will notice it not doing anything and helpfully optimize it away. So
your users in production will see your layout bug and you'll never be able to
reproduce it in development.

JavaScript is awesome.

As to the article itself, I'd prefer to see a comment on a line as wacky as
this one. It's one well-intentioned lop away from vanishing from that git
blame entirely, and then six hours of debugging and research away from finding
its way back into place.

Trying to sift through file history to understand what's going on is hard
enough on code I wrote myself only a year ago. I wouldn't want to rely on it
as the only way of digging into a large shared code base. Yikes.

~~~
tetha
> But if you're going to do this trick and you use a code compiler of any
> sort, you'll need to assign the value of that clientLeft somewhere.
> Otherwise your compiler will notice it not doing anything and helpfully
> optimize it away. So your users in production will see your layout bug and
> you'll never be able to reproduce it in development.

This optimization is only possible if the compiler is able to deduce this as a
useless function call. In order to do that, the compiler has to deduce (i)
that the result is not used, and (ii) that the function has no side effects.
(ii) can be very, very hard to deduce.

~~~
jasonkester
I don't disagree. But I post this because it actually happened to me. Googles
closure compiler to be specific. The only way to make it happy was to actually
assign the value to the window scope, where it couldn't know whether the value
was ever used.

------
martincerdeira
You live in a world of wonder and magic. If someone puts that code (without
comments) probably, the same person won't give such a detailed commit message.
Good luck in wonderland.

------
stretchwithme
It would be useful to make commit comments on code as you make changes that
can be used by SCMs and IDEs. See the history of a method change by change
complete with the relevant comments. And from an SCM, click on a comment and
select from a list of code changes.

And you avoid having to write your comments when you commit. You'd do it in
the code when you are more focused on the change.

Even better would be detecting when you are changing code and prompting for
the comment or let you select from recent comments.

Then on the SCM side when you commit, each comment could be handled as a
separate commit.

Any IDEs already doing some or all?

------
etler
This is exactly why I'm such a bastard when it comes to git history. A clean
history isn't something that just gets filed and disappears forever.
Unfortunately, lots of people think it's ok to use a message like "fixed
stuff". Don't even try that in my codebase though.

~~~
Zitrax
Or totally empty commit messages.

~~~
j-kidd
Here: [http://trac.imagemagick.org/log/](http://trac.imagemagick.org/log/)

~~~
dkuntz2
That pains me.

------
Roboprog
Mostly a good article. I would put more emphasis on using history/annotate
("blame") for timeline and _summary_ information, and using the inline
comments for _detail_ information.

Others have mentioned the "no comments" culture. To them I say: each
file/class and each function/method/subroutine should have a summary comment,
so I can know to skip over the irrelevant modules when I am looking for how to
do something. I don't want 80 to 100 character identifiers
(getMatrixResultButNotCornerCaseANorCornerCaseB or some such ridiculous name),
but I do want a bit more summary than the name, contained within a statement
of purpose comment.

------
erichocean
When I'm evaluating a project on GitHub, one of the first things I do is walk
through the commit history. The info in there is invaluable IMO for getting up
to speed on a codebase fast.

------
ithkuil
Sometimes it happens that code is moved between repositories in a way that
doesn't preserve each single commit.

DVCSs are designed to overcome this problem, and there are bridges between
various DVCSs, but sadly this still happens.

So, while mastering '<yourvcs> blame' is certainly useful, you shouldn't rely
too much on it, and write readable and well documented code.

------
chrisbumgardner
For fun I just created a Sublime Text 2 plugin that lets you bring up the git
blame->show for selected line(s) of code with a simple shortcut (cmd+shift+m
on Mac, alt+shift+m on Linux/Windows):
[https://github.com/cbumgard/GitCommitMsg](https://github.com/cbumgard/GitCommitMsg)

------
LukeB_UK
Every line of code is always documented (if it's in a VCS and the commit
message is good)

------
ilzmastr
Interesting concept. Coincidentally, I wrote a gem recently that serves the
same function as the git-overwritten script at the end:
[https://github.com/ilyakava/stefon](https://github.com/ilyakava/stefon)

gem install stefon

------
Aga
Extending code review to commit messages is a big help.

If I can't understand from the commit message, what the change is trying to
achieve, I won't even look at the code. Instead I'll ask to clarify the commit
message first.

------
gizmogwai
I wish my current coworkers wrote any comment in there commit message...

~~~
darryl42
I wish management allowed comments. Commits are work item number and title or
work item only. Comments in code are actively removed.

~~~
Roboprog
Fascinating: they care enough to consider such things, but they have made an
insane decision.

Good luck there.

------
forrestthewoods
Perforce time lapse view is similarly amazing.

------
ghubbard
"is it safe to change or remove that call in the future?"

If you remove the line you should end up with a failing test.

~~~
laureny
Good luck writing a test that makes sure that the CSS animations get properly
triggered on select browsers.

------
jheriko
good work. not enough people who use source control really seem to know what
its for...

whilst i'm a big fan of making code good enough to read - and learning to read
code properly - its easier to not have to do both

------
tshadwell
Is this Javascript? Why is there no semicolon?

~~~
Roboprog
Despite advice to the contrary, Javascript is a line oriented language and you
only _need_ the semicolon if you intend to stack a second statement on the
same line (kind of like colons in BASIC)

Yeah, I know that's blasphemy, but it's also true: Javascript works just fine
WITHOUT all the extra semicolons. The semicolons are only needed in the minds
of those who have been misled to believe that they are. One should learn what
JS thinks are complete statements -- where to wrap longer statements without
causing an error -- as Javascript WILL end statements without semicolons.
Better to just never use semicolons in the first place.

And this is all off-topic...

