php (split)

[Tank Program]

Thought I'd explain this better because I didn't make it explicit. About the diffs, is that if the comment on the same line, when I change the comment because I'm updating the explanation it visually looks in a tool like xxdiff or meld that I've changed the code as well, which often isn't the case. Instead it's things like punctuation, spelling, etc.

Interesting about OS X Jonathan. I'd never noticed it specifically before, but thinking about it I know exactly what you're talking about. Height does suggest importance, but to my mind one line to explain a line is a good importance rating. If it needs an explanation surely it's important enough for some height then. (Or maybe that's just circular thinking?) And again, if it's important enough to rate a comment, some extra spacing around it to differentiate is probably worth it so that you can find it again quickly later. It's probably all just personal preference. Something like this I think of as normal:

Code: Select all

			// get the colors from the pre-calculated color matrix
			$height_index = colorIndex($image, $coloring[$c][$d]);

			// override in case of special items in landscape
			if (isset($contents[$c][$d][0]))
			{
				if ($contents[$c][$d][0] == 1)
					$height_index = $gray;
				else if ($contents[$c][$d][0] == 2)
					$height_index = $waterblue;
				else if ($contents[$c][$d][0] == 3)
					$height_index = $sandyellow;
			}

Of course I say all of this, look back at old code and find things like this still:

Code: Select all

				$averageY0 = $average + $bHeight + 5 * $scale * cos($angle/180 * M_PI); // back
				$averageY1 = $average + $bHeight - 5 * $scale * sin($angle/180 * M_PI); // on the right
				$averageY2 = $average + $bHeight + 5 * $scale * sin($angle/180 * M_PI); // on the left
				$averageY3 = $average + $bHeight - 5 * $scale * cos($angle/180 * M_PI); // front

So I'm obviously not very consistent about it. In general everytime I've posted in this thread I've been unable to find that exact example I'm sure that I've just written somewhat recently....

Hurrah! Here's something that's recently written and has a crap variable name!

Code: Select all

        // 2 consecutive vertical pixels
        t = ((float)data[d*x + line] + (float)data[(d - 1)*x + line]) / 2.0f;

Here I'm using t (a float) to get the average of two ints. I think it's partially turning out that I just don't comment as much as I think I do. I suppose it, er, makes it more exciting later on...

Which is why I guess I have such fun gems lying around:

Code: Select all

		boolean dead = false;
		dead = selfCollide(dt);
		dead = dead | collide(grid.getWalls(), dt, false);
		for (int j = 0; j < grid.getPlayers().size() && !dead; j++) {
			Cycle player = ((Cycle) grid.getPlayers().get(j));
			if (id != player.getId() && !player.isDead()) {
				dead = dead | collide(player.getWalls(), dt, true);
			}
		}

A nice fun optimisation on boolean dead to terminate the for loop early, and some nice xorg usage to meet any one of the test conditions. Fortunately I was only working on this a few months ago. Ask me again in 2 years and I'll probably be stumped. *sigh*

Comments are good, however you do them. That or write dead obvious code.

[Jonathan]

Thought I'd explain this better because I didn't make it explicit. About the diffs, is that if the comment on the same line, when I change the comment because I'm updating the explanation it visually looks in a tool like xxdiff or meld that I've changed the code as well, which often isn't the case. Instead it's things like punctuation, spelling, etc.

Interesting about OS X Jonathan. I'd never noticed it specifically before, but thinking about it I know exactly what you're talking about. Height does suggest importance, but to my mind one line to explain a line is a good importance rating. If it needs an explanation surely it's important enough for some height then. (Or maybe that's just circular thinking?)

Elevation would more accurately describe what I meant. But I suppose if something is important, it will have a verbose comment, which will naturally be large. That should cover most of it.

Anyway, that's why you'd place comments above lines of code instead of beneath them. It's also a more natural order to read, which may even mean roughly the same thing. It should be a comment introducing a piece of code, not a puzzle followed by a hint (maybe even a solution written umop apisdn).

Comments at the end of the line aren't necessarily terrible from a readability perspective. They should only describe a single line anyway. But I find they don't stand out as much, or at least it takes more work. Also, lines are often long enough without a trailing comment. I suppose it could work as parallel commentary next to the code, IF everyone uses a wide window and rigid space-based indenting, and takes the trouble to align it all. I avoid it unless it fits well.

As for your code, I could make sense of most of it (not the coloring thing, which I'll generously attribute to lack of context), but, uh, it's not what I would've done. The first thing I'd change is the duplication of expressions and related cleanup. Beyond that I can't really tell from snippets, and I'd probably feel guilty about my own code if I dissected it too much. I have my own weaknesses.

Comments are good, however you do them. That or write dead obvious code.

Just avoid writing code that would leave you stumped if you didn't have comments all over.

[nux]

Comments at the end of the line aren't necessarily terrible from a readability perspective. They should only describe a single line anyway. But I find they don't stand out as much, or at least it takes more work. Also, lines are often long enough without a trailing comment. I suppose it could work as parallel commentary next to the code, IF everyone uses a wide window and rigid space-based indenting, and takes the trouble to align it all. I avoid it unless it fits well.

Well, some comments dont need to stand out, they should only be seen by somebody looking for them. If, for example, you are adding the original formula for a math issue, it should only been noticed when you are improving/fixing the formula with all the code variables. I guess it all depends on each individual case.

[Jonathan]

It's just that it seems like garbage at the end of the line. I find it's often a little chaotic and somewhat harder to read as a whole. But if it works, sure, do it.