I think that it's easy to say, "I know what MY code is doing". I should certainly hope that having written the code you have some idea of what your code is doing, however, if you're talking about a multi-programmer project or an opensource project, the issue becomes making sure that everyone knows what you're up to so that there aren't any gigantic crashes because someone didn't understand a function properly. Maybe it's my lack of experience, but I think that if you clearly lay out what you're doing and how, then everything becomes more self-evident. Your variables and functions aren't necessarily native to me or my experience, and therefore, it's easy to assume that I should just know what you're talking about.

However, once again, it may just be my lack of experience talking, since I don't really work with anyone or share my coding, and it's not really all that complex to begin with since I'm only in my baby steps. I do agree that you don't need to comment every line of code, because some stuff is quite clear, however, if it's a complicated function or something, why not make sure that it's crystal clear why it's doing what it's doing and how it's going about it? What harm does it do you other than an additional few seconds here and there to write a line of comment instead of a line of code?

Vopisk

Quote:Original post by Vopisk
I think that it's easy to say, "I know what MY code is doing". I should certainly hope that having written the code you have some idea of what your code is doing, however, if you're talking about a multi-programmer project or an opensource project, the issue becomes making sure that everyone knows what you're up to so that there aren't any gigantic crashes because someone didn't understand a function properly.

Of course. This isn't the issue though. You'll note that I didn't just strip the comments from his function ("I know what it's doing"), I completely renamed most of the variables, and refactored the swap out into a standard library function who's name makes it obvious what's happening ("The code explains what it's doing").

Quote:Maybe it's my lack of experience, but I think that if you clearly lay out what you're doing and how, then everything becomes more self-evident. Your variables and functions aren't necessarily native to me or my experience, and therefore, it's easy to assume that I should just know what you're talking about.

Again I say: "Instead of writing comments to say what zjfire stands for, make the code itself more verbose". It's literally harder to read, for me, the original version, because I have to ask "what is x?". In my code, it's obvious - left_sortee is the sortee "on the left" (of the array). I don't have to look at some comment and translate what's being said there into an understanding of what that piece of code is doing, just to single out exactly what x represents to answer the original question. As is, it took me awhile to rewrite that function because I had to do just this - ask what x represents (since I have no experience with the manual implementation of sorting functions).

Quote:I do agree that you don't need to comment every line of code, because some stuff is quite clear, however, if it's a complicated function or something, why not make sure that it's crystal clear why it's doing what it's doing and how it's going about it? What harm does it do you other than an additional few seconds here and there to write a line of comment instead of a line of code?

Comments can be used as an excuse for sloppy, harder to read coding. They have their places, but a lot of the time it screams "refactor me" or "name me better". Considering comments are mainly an aid to mantinence (bugfixing, refactoring, extending, etc) they should be used to help do this, rather than an excuse to make it harder. And a useless comment actually gets in the way of readability.

For example, when I was first learning C++, I was taking a class in the language. Being a young and immature lad of ~12 years, when the other similarly immature lad (it was a summer school thing) next to me showed me his code, imedded with insults against me, I immediately retaliated in force. One copy and some 50 pastes later, I was certain that anyone reading my code would be sufficiently well warned that he was an idiot, or reading my code through a preprocessor.

Of course, it turns out my program had a bug. When the instructor came to help me, he could not. The comments were too distracting for him to tell what was going on in my code - not for lack of trying. After removing the comments, he was able to deduce my problem.

[Edited by - MaulingMonkey on September 11, 2005 2:54:17 AM]

Quote:Original post by sirGustav

Quote:Original post by Vopisk
....so that there aren't any gigantic crashes because someone didn't understand a function properly.

IMHO there shouldnt be any crashes at all because of a faulty parameter.

IMHO there shouldnt be any crashes at all.

Fact is, most bugs arise from misinterpretation of variables or functions or outright frogetfulness. If you make your code idiot proof, someone will make a better idiot. Chances are that'll be you once in a blue moon.

It's all fine and well to try and prevent that, but it's not a good reason to not try to prevent such misunderstandings from occuring.

Okay, so, having gone back and taken a second look at what we're dealing with and the original snippet that was the subject of this little back and forth, I do agree with you MaulingMonkey that making your code easier to read is always a good idea. However, I will stick by my guns on this one when I say that for a complex function (that is something a bit more complex than a bubble sorting algorithm, which I'm pretty sure that was*) some additional in-function commenting can be a benefit to a user/programmer other than the original writer of the code, and most certainly, if I wrote a function with x, y and t as my variable values and went back to it a year later or something, would probably have no idea what any of them stood for, my memory just doesn't work that way.

However, as I said also, I've seen some horrible examples of coding and commenting, where the functions are not only archaic but the comments are too and there's no clear distinction what exactly anything is doing. In this case, perhaps the commenting does get in the way since it is not helpful. Perhaps it is best to just write a commented function header that explains what it does, where the parameters come from, etc... etc... whatever comments you need outside of the function. I don't really know, I haven't considered my personal style of commenting too far as I said I'm only just beginning with my programming. But this thread has certainly given me some things to think about.

Vopisk

Quote:Original post by Inmate2993
Okay, I'll allow that using self-documenting code is a good idea. One letter identifiers should almost never be used. However, its probably a big mistake to use self-documenting code as a replacement for well-documented code. The idea behind commenting is so that people will read the comments to understand what a particular group of lines do. Assuming that they'll know automatically what a block of code does just by reading it, thats what leads to poorly-documented code. Always assume that the code's function isn't obvious.

Prehaps, although I'm still going to stick by my own comments. For me, this is more readable:

distance = int( distance_between( point(x1,y1) , point(x2,y2) ) );

Again, I've taken something complex enough that it needs a comment and factored it out into it's own, well named and easy to understand function. I've also more visually grouped [x/y]1 and [x/y]2. This also eases optimization - if we want to take advantage of certain assembly codes, we could easily inject them within distance_between - in one place - rather than having to go helter skelter all over our code converting this that and the other.

If you want to do integer square roots in that manner, you can factor that out as well, possibly using template specialization.

[Edited by - MaulingMonkey on September 11, 2005 5:47:35 PM]

I find this is quite useful for UML, code generation and documentation + you can add to it.