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

41–50 of 104 posts

Re: Every line of code is always documented

#41

Post by geoka9 »

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.

Re: Every line of code is always documented

#42

Post by HeyLaughingBoy »

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. I found myself thinking WTF as I read the article. Maybe I'm showing my age, but the project I just switched from (and still have to consult on from time to time) was started in the late 90's and probably won't be retired for at least 10 more years. I have found myself not just looking through version control history to understand the change history of a file to find a bug, but tracking it over multiple version control systems as the project matured.

Re: Every line of code is always documented

#43

Post by ghayes »

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.

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.

Re: Every line of code is always documented

#44

Post by hermannj314 »

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.

Re: Every line of code is always documented

#45

Post by j-kidd »

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 plus full explanation in the commit message. For hard-to-read code with complicated logic, I'd go with long comment in the code. Or refactoring.

Ticket description, commit message, code comment, and the code itself are all necessary to keep the codebase "documented".

Re: Every line of code is always documented

#46

Post by j-kidd »

Zitrax wrote: post #29
etler wrote: post #6

This is exactly why I'm such a bastard when it comes to git history. A clean history isn't something that just gets filed and disappears forever. Unfortunately, lots of people think it's ok to use a message like "fixed stuff". Don't even try that in my codebase though.

Or totally empty commit messages.

Here: http://trac.imagemagick.org/log/

Re: Every line of code is always documented

#47

Post by zmmmmm »

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 history. If I check them in all together do I type a whole essay into the revision history about why each change was made in each file? It'll quickly all fall apart.

It also relies on the reader recognizing that they need to be curious about the code here. What it if didn't look so curious? It could easily get cleaned up or modified without a comment to alert the reader.

For people and projects in specific contexts it can work but there are plenty of situations where this is a terrible idea.

Re: Every line of code is always documented

#48

Post by shawnz »

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…

It seems that this was the only instance of its use in the whole codebase. I certainly agree that a comment should have been placed there, and of course creating a function would be the most idealistic solution. But I think that, without knowing the specific context, it is hard to say whether creating a function would have been an improvement or detriment to the code -- especially considering it is just a single line of code.

Re: Every line of code is always documented

#49

Post by mattdawson »

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…

Totally agree with the "might me good for maintenance mode" sentiment. I'm working on a pre-1.0 project. I'm thinking about the few commits where I was first implementing localStorage caching. Tons of files were effected on each commit. If there was a particularly tricky line in there (there were several), how would I have specified it in a commit? That'd be extremely hard to read when compared to the alternative of putting the comment above the code.

Re: Every line of code is always documented

#50

Post by _delirium »

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