Every line of code is always documented • Hacker News Board

Re: Every line of code is always documented

#101

Post by mislav » Mon, Feb 10, 2014, 3:29 AM UTC

etler wrote: post #13

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…

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

Thanks for your words of defense, etler. A lot of the criticism of my original post was valid, though, so I addressed it by rephrasing and stressing out that code quality still matters: https://github.com/mislav/mislav.github.com/commit/e07907966...

You were right, however, that the post was never about code quality or code comments. It was only about "history's great, yo; here's what you can do with it".

Re: Every line of code is always documented

#102

Post by jasonkester » Mon, Feb 10, 2014, 9:48 AM UTC

tetha wrote: post #83

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…

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.

Re: Every line of code is always documented

#103

Post by chrisbumgardner » Mon, Feb 10, 2014, 10:12 AM UTC

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

Re: Every line of code is always documented

#104

Post by jakejake » Sat, Feb 15, 2014, 12:24 AM UTC

tsiki wrote: post #80

jakejake wrote: post #38

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

I think it has something to do with the idealistic view of "pure, well-written" code. There's something appealing about a code base consisting of only code, not comments. But in my very subjective experience, I've noticed that the more programming experience people have under their belts, the more likely they are to appreciate commenting as a tool among other tools to make your code readable.

I think that's a very good point and it seems to me the spirit of that argument is "write code that is so clean that it doesn't need comments." Or the inverse of that could be "if your code needs a lot of comments then it probably isn't very clean."

So I think that is a good mentality in as much as it keeps you thinking and writing clean code. But, I think it's also rather presumptuous to assume everything will be clear to others. Also as you say - once you've had to stick around and maintain a few applications, you really appreciate a thoughtful programmer who put in some comments that saved you a few hours. And you start to loath the rock-star who came in for 6 months and wrote a bunch of code using the fad-of-the-moment design pattern without commenting anything.