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

31–40 of 104 posts

Re: Every line of code is always documented

#31

Post by etler »

jkrems wrote: post #24
etler wrote: post #8

Earlier quoted context omitted.

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…

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…

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.

Re: Every line of code is always documented

#32

Post by jpatte »

adamlett wrote: post #28
jpatte wrote: post #21

Earlier quoted context omitted.

But he is actually right: when dealing with obscure implementation details, the best thing to do is to encapsulate it properly, the minimum is to comment it clearly, and ideally detailed explanations should be written in the commit message. Having a detailed code history isn't in any way an excuse to leave obscure code as is. If you have time to document it, you have time to make the code right.

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 writing messy code like that is prohibited.

In short, maintaining a clean code base has always higher priority than maintaining a clean log.

Re: Every line of code is always documented

#33

Post by aidos »

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.

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.

Re: Every line of code is always documented

#35

Post by jpatte »

etler wrote: post #31
jkrems wrote: post #24

Earlier quoted context omitted.

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…

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.

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.

Re: Every line of code is always documented

#36

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

Re: Every line of code is always documented

#37

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

Re: Every line of code is always documented

#38

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

Re: Every line of code is always documented

#40

Post by geoka9 »

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…

Exactly.

My problem is that usually the people who neglect to write a comment in the code, also neglect to write meaningful commit messages. Usually it's just "fixed the layout bug" or something like this, along with a bunch of other unrelated changes all squeezed into one commit.

Post reply on HN