I changed my mind...
Damocles said:
Not a fair question really as it depends on the circumstance. I would do whichever would benefit the most. You can make the argument that any function that needs to have a number of complex calcuations in a series of loops is badly designed and needs a rewrite anyway. If I just had to change an index variable name to make it clear, I would obviously do this.
Fair enough. I always work within a specific convention, so if I name everything in a specific way.
Damocles said:
//i = age, j = grumpiness
Fair enough, I disagree that this is effective enough though.
Damocles said:
Disagree. If you have some functions that are hundreds of lines with multiple loops, you need to rethink the design of the section. I know it happens on codebases over years as programmers and requirements change but we are arguing a perfect world scenario here.
For the project I'm currently working we have some highly optimised algorithms, the functions for which cover several hundred lines. It wouldn't be appropriate to subdivide these into further functions as there aren't any appropriate subdivisions to be made. We also have some legal restrictions on how certain calculations have to be made. That said, I was using the 200 figure simply to give a number that would entail scrolling. If I had to scroll or click something to find out what a variable was supposed to do I'd want it renamed so I didn't have to.
Damocles said:
Agree but here we go back to my earlier point. Also, a combination of a decent debugger and IDE will solve this problem. Right click->Find Definition.
The problem with this is that if, say, you performed three loops one after the other i would have a different meaning depending on which loop it was in. You'd have to keep checking which loop you were in or checking your definition again. We develop our code to be easily human-readable, in that you can work out what it does just by reading it like a book with no knowledge other than an understanding of the syntax.
Damocles said:
These scripts are literally useless. One of the most basic ideas about commenting is that it should describe what the code is doing and not describe the code itself. Saying
Code:
//remove bottle from wall
for(int i=0;i <10;++i)
{
Wall.RemoveBottle(i);
}
is literally the most useless thing you can say. It is self evidence that a call to RemoveBottle will remove a bottle.
The self producing documentation should only be used as an addition to a decent commenting system, not as a replacement for it.
I agree, and we comment the code too. These comments also pull through into the documentation. The automated documentation is simply the bones around which the final code documentation is produced.
Damocles said:
I agree when we're talking about the naming of classes, objects, functions, and variables which have large scope. But we're talking about variables that have local scope to the loop and disappear after. If you're writing nested loops where it isn't obvious what i and j are doing, it is your method names and commenting you need to work on; naming the index variables is putting a plaster on a broken knee.
I disagree that there should be any distinction between the two. A variable is a variable regardless of scope and should be named per your variable naming convention. Ours is scope (global, module-level, etc.), type (bln, int, str, etc.) then name, i.e. strName or gblnReadOnly. This applies to every variable that is defined.
I don't agree that losing track of the meaning of i and j means the method names and comments need improving. Where possible you break down functionality into it's component functions, but there comes a point when it can't be broken down any further. That point isn't always the point at which each function does only one thing as there are often scenarios where multiple things are intertwined and need to be performed together in such a way that breaking it down into separate functions would actually increase complexity.
Your answer to that will probably be along the lines of "well if the code became too complex I would use more descriptive names instead of just i or j", though feel free to disagree if it wouldn't be as I don't want to speak for you. Therein lies the difference in our opinions, as mine is that I would rather it be done the same way throughout so that we know everyone's expectations and understandings will align. With multiple developers it would be difficult to ensure that the line at which you stopped using i and j was one that all found suitable as one developer might think a particular block of code was more complex than someone else thought it was.
