I don't like it (PostgreSQL example) because you can't see big picture but must scroll up and down until you understand.
And human tends to put ambiguous comments. so i just don't read it if i don't have to.
Comments that contains examples of input and output, current state of variables can be helpful. or things like that.
So more compressed code is ok, because it has more data displayed in more convinient form. It is same thing for displaying other kinds of data besides code.
But i may also be n00b. so take this with grain of salt.
I find the PostgreSQL example great. The big picture is given to you by the function comment. Scrolling is just a side effect...you can get around it by a good IDE.
yep true, but i meant "big picture" of that particular function, poor choosing of words. but it would be more cool if you somehow would be able from one function see big picture of whole project like in fractals or some thing. :-)
I'm pretty sure that if I were to start contributing to that codebase I'd be really happy that those comments where there. However I'm also pretty sure that as I learned the code I'd be less happy about them and prefer to be able to see more of a function on a single screen. So maybe n00b-hood applies to code bases too.
I also think that some of those functions are too large even without their comments, exec_simple_query is gigantic.
It is also worth noting that comments have less contrast on github and in most other IDEs. I think it speaks to the fact that humans and computers actually care about the same parts of the code file.
And human tends to put ambiguous comments. so i just don't read it if i don't have to.
Comments that contains examples of input and output, current state of variables can be helpful. or things like that.
So more compressed code is ok, because it has more data displayed in more convinient form. It is same thing for displaying other kinds of data besides code.
But i may also be n00b. so take this with grain of salt.