Quote:
I told him he needs to use descriptive variables and he told me he likes to be annoying to the TA's (graders). I guess he doesn't realize they give him a grade on that stuff.

Quote:
// Increment i
i++;

I guess it could be useful. You might just on the off chance have somebody that doesn't know the programming language being used at all reading it

Quote:

Generally speaking, your code should speak for itself, if it isn't then there's something wrong somewhere! I know that in practice this isn't always possible, but when I come across a situation like this, a single line comment usually suffices.

Quote:
Slighty OT but....

I've never really understood why some people get majorly obsessive about commenting code - I don't know how many times I've heard "code without comments is bad".

Generally speaking, your code should speak for itself, if it isn't then there's something wrong somewhere! I know that in practice this isn't always possible, but when I come across a situation like this, a single line comment usually suffices.

Like above, giving variables and functions proper descriptive names is about the biggest favour you can give yourself and others who access the code.

Bad code is bad code, no amount of commenting is going to fix it!

Quote:
I've never really understood why some people get majorly obsessive about commenting code . . Generally speaking, your code should speak for itself, if it isn't then there's something wrong somewhere

for (i=0; i<Accounts.Count; i++)

{

  Accounts[i].Process();

}

Quote:

Execution speed and program size are no longer top priorities.

Quote:
Yeah...that's basically what I said in two lines about documenting business logic

Yeah it was- I've developed a bad habit of posting before finishing reading the thread. It's bitten me twice now recently. Once I realized it, though, I wasn't going to delete all of that.

Plus, I'm longwinded!

Quote:

Quote:

Execution speed and program size are no longer top priorities.

I've been hearing that myth for 25 years now, and it just never holds water. Unless one doesn't mind having to continuously purchase newer faster hardware to keep up. Ugh.

And of course, the segment I work in -- embedded operating systems -- speed/space are always THE most important thing, after having a working implementation of course.

Cheers

Quote:
Consider the following code:
Code:

---

for (i=0; i<Accounts.Count; i++)
{
  Accounts[i].Process();
}

---

This seems farily straightfoward code, so a comment like "//Loop through our accounts and process them" is not useful. We can see that from the code. However, a comment telling us what the real-world problem is that we're trying to solve is helpful in understanding the bigger picture: "//Calculate new monthly values for each of our accounts based on current market values".

Quote:
But I wouldn't be calling the member function "process", I'd be naming it after what it does, therefore a comment wouldn't give me anymore information than what the line of code does! :P

Quote:
hmm...

Accounts[i].calculateNewMonthlyValueForOurAccountBasedOnCurrentMarketValue();

seems a bit verbose...

Quote:


Quote:
hmm...

Code:

---

    Accounts[/i].calculateNewMonthlyValueForOurAccountBasedOnCurrentMarketValue();

---

seems a bit verbose...



So? That's what Intellisense (or whatever it's called in your favourite IDE) is for.

Quote:
But I wouldn't be calling the member function "process", I'd be naming it after what it does, therefore a comment wouldn't give me anymore information than what the line of code does! :P

Quote:
All the apps I like to see use stored procs, but my requirements are not performance based, but security based, and it is much easier to meet FSA requirements with a limited set of stored procedures.

Quote:
It is so common to see an app which appears secure at first glance but is vulnerable to a simple SQL Injection atack, thus rendering all the front end security laughable.

Quote:
I understand about the code speaking for itself, but most of the time code can really only speak about the HOW, not the WHY.

Quote:

Quote:
I understand about the code speaking for itself, but most of the time code can really only speak about the HOW, not the WHY.

This is soooo important. One of my functions at work is to review code written by the rest of our department members. I can't count the number of times that I've seen code that makes me go "huh?" -- the code may be "self-documenting", but not doing what I think it should be doing. The first question I'll usually ask is "why are you doing this?" Sometimes the answer is "well, I tried doing it this [what I would have expected them to do], but it had a problem that doing it this way avoids," to which I'll say "Maybe you could add a comment to that effect, so that whoever maintains this code after you doesn't waste time by ripping it out, and trying to replace it with that." Sometimes I just get a shrug, or an answer that isn't very well thought out -- those are the cases that tell me that a) the developer didn't spend much time thinking about the design, or b) the developer doesn't know the language well enough to know a better way to do it, or c) the code is probably buggy. I've caught a lot of buggy code as a result. [/QUOTE]

Quote:

Quote:
Further, "self-documented code" is sometimes just wrong -- you start out with a function named one thing, which then gets minorly modified so that it subltly doesn't quite live up to its name, but no-one changes the name of the function, because it's an API, and you don't know who else is using the function. Personally, I've never seen any non-trivial so-called "self-documented" code where the "self-documenting" is as complete as it needed to be.

The name of the function might lie, but the code inside it wont.

Now, suppose there's a bug in the code, so that it's doing something yet even more different -- you have a function named for something it's not really doing, the original programmer's intent is to do something that the code's not actually doing -- without a comment explaining what the intent was, are you, the maintainer, going to guess at the code's intent, or just incorrectly fix it to do what the name of the function is?

Quote:
I don't see how a comment could be any better, after all your programmer might forget to change the comment, or the comment might get shifted from its original place after code edits, imho it's far easier to get comments out of sync with code than "code"!

That's partly why it's so important -- if the comments match the code, then you know it's more likely things are hunky-dory. If the comments don't match the code, then you and the developer need to have a chat, because it's an indicator that he didn't write what he intended to write.

In addition, tons of research has been done that shows commenting code does improve maintainability and code readability. Welcome to the field of software metrics analysis. Several years ago, I spent 8 months as an intern with a the Software Engineering and Analysis Lab at Nortel (I can't find an external web-presence for them, but there's an description for them here).
Lots of statistics; I couldn't hack it, and had to get out.

In general, I treat blocks of code as a paragraph, and, just like paragraphs have an introductory sentence, I typically add a summary comment about what the block of code is supposed to be doing, and why. Line-by-line commenting is excessive, and metrics analysis shows that too much commenting can be just as bad as too little.

Quote:
The name of the function might lie, but the code inside it wont. I don't see how a comment could be any better, after all your programmer might forget to change the comment, or the comment might get shifted from its original place after code edits, imho it's far easier to get comments out of sync with code than "code"!