Every line of code is always documented • Hacker News Board

Re: Every line of code is always documented

#81

Post by jasonkester » Sun, Feb 09, 2014, 9:52 AM UTC

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.

Re: Every line of code is always documented

#82

Post by einhverfr » Sun, Feb 09, 2014, 9:59 AM UTC

tsiki wrote: post #79

einhverfr wrote: post #64

Earlier quoted context omitted.

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.

>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?

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

Re: Every line of code is always documented

#83

Post by tetha » Sun, Feb 09, 2014, 10:47 AM UTC

jasonkester wrote: post #81

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…

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

Re: Every line of code is always documented

#84

Post by tetha » Sun, Feb 09, 2014, 10:52 AM UTC

ghayes wrote: post #43

geoka9 wrote: post #41

Earlier quoted context omitted.

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

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.

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

Re: Every line of code is always documented

#85

Post by stcredzero » Sun, Feb 09, 2014, 11:59 AM UTC

RyanZAG wrote: post #9

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 hist…

I was recently watching a talk given by Rich Hickey where he talks about serialization formats and how they can have all their metadata in-band or have to depend on out of band information. The latter situation is where bugs can be introduced.

The example in the original post relies heavily on out of band documentation. Your suggestion of an intention revealing function name puts the same info in-band.

One should always ask themselves: Does my code depend on out of band information? If so, can we correct this?

Re: Every line of code is always documented

#86

Post by stcredzero » Sun, Feb 09, 2014, 12:02 PM UTC

RyanZAG wrote: post #15

etler wrote: post #13

Earlier quoted context omitted.

"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…

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.

basic code design: put your stuff in function

Aye, and with intention revealing names!

http://c2.com/cgi/wiki?IntentionRevealingNames

Also: http://c2.com/cgi/wiki?LawOfDemeter

Re: Every line of code is always documented

#87

Post by jheriko » Sun, Feb 09, 2014, 12:04 PM UTC

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

Re: Every line of code is always documented

#88

Post by ithkuil » Sun, Feb 09, 2014, 1:27 PM UTC

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 ' blame' is certainly useful, you shouldn't rely too much on it, and write readable and well documented code.

Re: Every line of code is always documented

#89

Post by pseut » Sun, Feb 09, 2014, 1:56 PM UTC

zmmmmm wrote: post #47

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 h…

Honestly, I think your example is a better demonstration of this than the article's. You make a change in four places, make a single commit, and then someone reading the code later can use the VCS to find all of the relevant parts of the code that deal with any particular line they're looking at.

Re: Every line of code is always documented

#90

Post by markm208 » Sun, Feb 09, 2014, 3:20 PM UTC

icebraining wrote: post #58

markm208 wrote: post #51

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 sto…

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…

Imagine if the author of the novel had to write those irrelevant scenes anyway in order to get to the good stuff. There might be someone, a literature academic for example, who would want to study that material. It wouldn't be for everyone but there are some who might want access to it. My point is that we are generating this history anyway, so why throw it out? There may be someone who wants to see how the code has evolved. Plus, nobody says you have to watch stuff that is not interesting. There are ways to filter out things you aren't interested in.