28 Mar, 2010, David Haley wrote in the 21st comment:
Votes: 0
Shasarak said:
Yeah. And that's not in the least arrogant, patronising or insulting.

Yes, well, to be honest it was meant to point out the silliness I found in what you'd initially said, which wasn't in the least arrogant, patronizing or insulting either. You may consider it responding in kind if you will. :wink: FWIW, I don't view it as "scoring points" to point out that what you're saying is hyperbolic: I think it usefully advances the discussion to say why I think you were making rather bold claims (which is what I did). For somebody who's getting upset about arrogance, patronizing and insults, I think it's odd for you to at the same time make accusations as you did.

Shasarak said:
One thing which may be worth pointing out is that I never even mentioned API documentation. That's a different issue. Certainly an API needs to be documented; but putting comments in the code is quite possibly not the right way to do that. Comments in the code generally describe how something works internally, rather than how to use it. To put it slightly more formally: when you document an API, what you document is the public interface. Code comments become useful when you want to delve inside an API and find out how it does what it does - they describe the private implementation details.

Yes, well, API documentation is often written using comments, so I don't think it's a different issue in the slightest. FWIW, I already drew the distinction between external-facing comments and internal-facing comments.

Shasarak said:
If an API requires you to know its implementation details in order to use it properly, then that API has been written badly.

Not necessarily. There are many cases, typically related to performance, where implementation details can be very important. The API can, for instance, in some cases provide far better performance if operations are performed in this order rather than that order. You can still use it "properly", in the sense of "correctly", without following that order, but knowing the implementation details can dramatically improve performance.

flumpy said:
I don't understand what you mean, I am guessing you are just being snide again. (…) However, I guess your kind of code is different, and you perhaps like to revel in the complexity of it: each to their own.

Hmm…… :thinking:
You're right: you didn't understand what I meant and instead, because you seem to be feeling touchy, chose the interpretation that makes what I said the dumbest possible.
28 Mar, 2010, flumpy wrote in the 22nd comment:
Votes: 0
David Haley said:
You're right: you didn't understand what I meant and instead, because you seem to be feeling touchy, chose the interpretation that makes what I said the dumbest possible.


TBH I wasn't actually attacking you with that statement (hard to believe? perhaps). I was in fact commenting on the reality I find myself in daily.

If you have to comment your blocks so you can see where these blocks end you're doing something poorly for the next guy to have to deal with… It's far harder to read and debug if you have a lot of nested code blocks and "// end of wossname" comments just add to the messiness IMHO.

Code complexity != length. The length of the block has nothing to do with it. What makes code complex is number of paths through the source, as I'm sure you understand, so I thats why I don't really understand your "have your blocks be small enough that "bouncing around" is just glancing up your screen" comment. I could have a very large method, with one path, that does only one or two things, and I would be happy with that. When my method does 3 or 4 things and has 3 or more if statements in it, I start looking at refactoring it.
28 Mar, 2010, David Haley wrote in the 23rd comment:
Votes: 0
I wasn't disagreeing that long blocks should be avoided when possible, or that it's silly to comment ends-of-blocks when they blocks are short. I was merely saying that sometimes, when you have a long block and it is difficult to split it up (mathematical code comes to mind, or other number-crunching), it is useful to note which process just ended. (Incidentally such blocks are typically both long and complex…)

flumpy said:
What makes code complex is number of paths through the source

Well, that's one form of complexity. There's also plain old complexity of the logic being implemented, even if it all takes place in a relatively small number of paths.

flumpy said:
so I thats why I don't really understand your "have your blocks be small enough that "bouncing around" is just glancing up your screen" comment.

That just meant that if blocks are small, you don't have to move around in the file to find where the block started because it's basically right in front of you already (assuming that the block is small enough).

flumpy said:
I could have a very large method, with one path, that does only one or two things, and I would be happy with that. When my method does 3 or 4 things and has 3 or more if statements in it, I start looking at refactoring it.

It sounded initially like you were opposed to long blocks, rather than large blocks within a block. Thanks for clarifying. I agree that commenting the end of a long function with "end of function" is sometimes silly, but even then I sometimes find it useful as a period of sorts marking the end of what just happened – it's a nice visual marker in languages that don't have explicit markers for the end of the block (like Python). Other languages with block markers obviate the need for this comment.
28 Mar, 2010, flumpy wrote in the 24th comment:
Votes: 0
I was thinking of python as perhaps an exception, yes. I still and probably always will dislike it in languages like java, I tend to think you should indent clearly enough not to be a problem.

And I agree with the cyclical vs mathematical complexity thing too, although I still would not comment my end of code blox with "end pythagorus' theorum impl" :biggrin: I'd comment at the start or at point in the middle.

I don't think we disagree as much as it seems sometimes DH, and I know I have plenty to learn from you so, there you go.
20.0/24