Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Every line of code is always documented

mislav.uniqpath.com

Post reply on HN
Print view View original

71–80 of 104 posts

Re: Every line of code is always documented

#71

Post by ryanpetrich »

meistro wrote: post #5

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

It's even easier to create three separate var statements and let a JavaScript compressor handle it:

    var one = "foo";
    var two = "bar";
    var three = "baz";

Re: Every line of code is always documented

#72

Post by mistermann »

kelnos wrote: post #67
adamlett wrote: post #19

Earlier quoted context omitted.

Way to miss the point completely.

I think he got the point. Just that the article is predicated on something incredibly stupid: someone writing a line of code that, to probably most people other than the author, is useless and incomprehensible. I think it's great that the author wrote a detailed explanation in the git commit message, but it's absolutely not enough. That piece of code needs at least a one-line comment there, full stop. I think the art…

> That piece of code needs at least a one-line comment there, full stop.

From my experiences in the real world and from reading comments here, I think there are a lot of people that disagree with that assertion, and it kind of makes me wish I worked in a field where I don't feel like I'm going insane on such a regular basis.

Re: Every line of code is always documented

#73

Post by mistermann »

geoka9 wrote: post #41
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…

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

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

Not only that, but I speculate that those holding such opinions are usually young, well above average programmers who therefore work exclusively on brand new projects - many of them have literally never experienced the nightmare of maintaining and extending some crap code written in the most clever and obscure way possible by someone similar to themselves. Hell, a lot of them likely don't stick around long enough to make major modifications to their own code.

Re: Every line of code is always documented

#74

Post by Dylan16807 »

gfodor wrote: post #54
jpatte wrote: post #32

Earlier quoted context omitted.

The premise of the article is that you happen to stumble upon a messy piece of code and that the explanations related to it might be located into the source history. Yet the only reason why these explanations would actually be there is that someone would have enforced doing that as a rule. And the point of the counter-argument is that before enforcing this rule this same person should be enforcing a rule saying that…

jesus christ http://lsolum.typepad.com/legal_theory_lexicon/2003/09/legal... this article is about recommendations of what to do ex post once a comment-less line of code has been committed in the past that you need to understand. arguments about ex ante things such as how it got there in the first place and how to prevent it from happening is completely orthogonal to the point of the article.

Strong disagree. The article is about recommending and making ex post use of a policy for good commit messages. The point argued is in favor of a future rule for good commit messages. Therefore it is very reasonable to suggest a superior rule for the future.

Re: Every line of code is always documented

#75

Post by Dylan16807 »

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…

If I have to later see every dumb thing I let within ten feet of my IDE window while working, I'm going to set the computer on fire and code pen on paper for later transcription.

Re: Every line of code is always documented

#76

Post by jakejake »

_delirium wrote: post #50
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…

Is that actually a widespread view? I though at least post-1970 or so, it was pretty standard practice to comment liberally. Going all the way to Knuth-style literate programming hasn't caught on, I'll admit, but I didn't think wall-of-code was widely admired anymore either.

It's been a while since I've seen a discussion on code comments here on HN but I have noticed in the past that there's a vocal group who are fairly passionate against code comments. I was actually expecting a wave of downvotes to my original comment.

Re: Every line of code is always documented

#77

Post by jpatte »

gfodor wrote: post #54
jpatte wrote: post #32

Earlier quoted context omitted.

The premise of the article is that you happen to stumble upon a messy piece of code and that the explanations related to it might be located into the source history. Yet the only reason why these explanations would actually be there is that someone would have enforced doing that as a rule. And the point of the counter-argument is that before enforcing this rule this same person should be enforcing a rule saying that…

jesus christ http://lsolum.typepad.com/legal_theory_lexicon/2003/09/legal... this article is about recommendations of what to do ex post once a comment-less line of code has been committed in the past that you need to understand. arguments about ex ante things such as how it got there in the first place and how to prevent it from happening is completely orthogonal to the point of the article.

As rymohr indicated, the author of the code given as example is actually the author of the article himself:

https://github.com/madrobby/zepto/commit/3d92f20966aa02dee82...

Which means the OP genuinely thinks that commits like this one are good practice, and the purpose of the article is to show how to deal with it.

Yet as it was argued above, commits like that should never happen in the first place.

Re: Every line of code is always documented

#78

Post by dkuntz2 »

akkartik wrote: post #70
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…

Most interesting. I recently did some work on a new, version-control-inspired layout for programs, but from a different angle than you suggest: http://akkartik.name/post/wart-layers . I'd love to chat more about the details of what you're trying (email in profile).

Two questions:

1. How is that different than functionizing things? And, is it better? Especially because in wart it looks like your snippets can only be used once.

2. Does this bring you any advantages that well commented code doesn't? From my admittedly limited point of view (I haven't run it, just looked at your two examples) it looks like following the flow of control is a little more difficult, because it looks like your snippets are, when compiled, just placed where their comments are. Because variables are accessible and manipulable in your snippets there isn't any containment like you get with functions.

Again, this is from me only looking at your two examples.

Re: Every line of code is always documented

#79

Post by tsiki »

einhverfr wrote: post #64
crazygringo wrote: post #56

Earlier quoted context omitted.

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

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?

Re: Every line of code is always documented

#80

Post by tsiki »

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.
Post reply on HN