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

51–60 of 104 posts

Re: Every line of code is always documented

#51

Post by 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

Re: Every line of code is always documented

#52

Post by _delirium »

j-kidd wrote: post #45
crazygringo wrote: post #37

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…

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…

If the codebase is associated with a reasonably stable bug-tracker, I'd also put a bug # or a URL in the source comment if it's something nonobvious that is important for future maintainers to be aware of, but considered too long to document inline (if it's purely of historical interest, then yeah, leave it to the VCS history). Or a link to an archived mailing list discussion, or a CVE id, or some kind of hint.

Re: Every line of code is always documented

#53

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

Re: Every line of code is always documented

#54

Post by gfodor »

jpatte wrote: post #32
adamlett wrote: post #28

Earlier quoted context omitted.

Of course he is right. But he still completely missed the point of the article, which was not to defend writing or keeping code that is not self explaning. I mean, it's the goddamn premise of the article that you happen to stumple upon a piece of code that's less than perfect! The example in the article describes a situation in which you find a piece of code someone else wrote and you are unsure of what it does or wh…

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.

Re: Every line of code is always documented

#55

Post by stavros »

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

I disagree with "liberally", as there's a cost associated with commenting (they have to be maintained and people have to spend time to read them), but I'm certainly of the opinion that judiciously commenting is very useful.

Re: Every line of code is always documented

#56

Post by crazygringo »

j-kidd wrote: post #45
crazygringo wrote: post #37

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…

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…

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.

Re: Every line of code is always documented

#57

Post by KMag »

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…

Exactly this, with the addition that there are actually three things I want to see when reading code, only one of which can often be elegantly expressed without comments.

I usually want to see (1) what the code does (2) what the code is intended to do and (3) why the code is intended to work that way. Usually only the first can elegantly and most easily be expressed in code.

For instance, I read a performance-critical function that would stop processing data and return early in an obscure corner case, but performed better than the best way I could think of to handle the obscure corner case. There were at least 3 possibilities: (1) the author made a mistake (2) for reasons I couldn't see, the corner case was impossible or (3) for reasons I couldn't see, the consequences of mishandling the corner case were never as bad as I thought they could be and the performance gain was worth it. I had to look up the revision history, call up the author and ask him which it was. It turns out the author had missed the corner case, but I try to as rarely as possible assume I'm smarter/more insightful than the original author.

Re: Every line of code is always documented

#58

Post by icebraining »

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, though those tend to happen in the REPL, not in the code editor), but I disagree with an indiscriminate approach.

Re: Every line of code is always documented

#59

Post by salgernon »

crazygringo wrote: post #56
j-kidd wrote: post #45

Earlier quoted context omitted.

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…

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…

Comments are frequently out of date with the code that they're describing. This tendency is somewhat linear with the length if a comment and therefore longer comments will be more incorrect, more quickly. I'm not being facetious, this is a readily observed phenomena.

Re: Every line of code is always documented

#60

Post by salgernon »

hermannj314 wrote: post #44
crazygringo wrote: post #37

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…

I concur. I've worked in enterprise. If your team relies on a centrally administered source control, then you can be in a world of pain if the central team decides to switch tools (and when this happens moving your revision history comments to the new system will never be considered important, if even possible). Keep important things in the code. That's my experience.

rcs -> sccs -> cvs -> svn -> git, with a trip through MPW Projector. Half the commit comments lately are "why the hell did git do this to me".
Post reply on HN