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"!

Quote:

What's next on the discussion list? Vi or Emacs? Code formatting style? OS distribution?

Yeah, while we're at it, anybody using K&R style bracketing needs to be taken out into the parking lot and shot. Harsh, but fair!

Quote:
Yeah, while we're at it, anybody using K&R style bracketing needs to be taken out into the parking lot and shot. Harsh, but fair!

Quote:

Yeah, while we're at it, anybody using K&R style bracketing needs to be taken out into the parking lot and shot. Harsh, but fair!

Quote:
I have been forced to use K&R style for the last two days

  if (x) {
    doSomething()
  }

  if (x)
    {
    doSomething();
    }

  if (x)
  {
    doSomething();
  }

Quote:
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:
It is all a balance. You need a concise function name and a concise set of comments. Just because the compiler gives you the ability to have a 255 char long function name doesn't mean you should have an insanely long function which describes exactly what it does. You shouldn't put a comment in for every single line either.

   Allman/BSD     Horstmann      GNU           Whitesmiths     K&R

   if (b)         if (b)         if (b)        if (b)          if (b) {
   {              {  x = 1;        {              {               x = 1;
      x = 1;         y = 2;          x = 1;       x = 1;          y = 2;
      y = 2;      }                  y = 2;       y = 2;       }
   }                               }              }

Quote:
I hate K&R Bracketing

if (x > y) then

begin

    statement1;

    statement2;

end;

if (x > y) then begin

    statement1;

    statement2;

end;

Quote:
Personally, I use K&R, though I disagree with Jeff's theory about how/why it evolved.

Quote:

So I'm assuming that when coding in Delphi, you use:
. . .

Quote:
Personally, I set my tabstops to 2 spaces and indent once for each K&R indentation.

Quote:
Are there any members of this BBS that are NOT programmers?

Quote:
tabstop should never be set to anything other than 8. You really should be using what vim calls 'softtabstop' (along with 'shiftwidth'), which allows you to edit as though a tabstop is 2 spaces, but leaves the tabstop definition at the standard 8 spaces.

Quote:
tabstop should never be set to anything other than 8.

GNU/Emacs freak.

Quote:
You really should be using what vim calls 'softtabstop' (along with 'shiftwidth'), which allows you to edit as though a tabstop is 2 spaces, but leaves the tabstop definition at the standard 8 spaces.

Quote:
I really hope you also have 'expandtab' set (which, for the non-vim users, turns tab stops to spaces).

Quote:

Quote:
tabstop should never be set to anything other than 8. You really should be using what vim calls 'softtabstop' (along with 'shiftwidth'), which allows you to edit as though a tabstop is 2 spaces, but leaves the tabstop definition at the standard 8 spaces.

I'm trying understand what you're saying here, but I don't get it (not a vim user if that matters).

I used the names of vim settings, since I believe Bitt mentioned using vi in another post, and it's the terminology I'm most familiar with.

A 'softtabstop' set to two spaces means that when you hit tab in the editor, rather than inserting a tab character, "\t", it will insert two spaces. Once you tab over a full tab stop, it replaces spaces with a tab character. This last behaviour is actually quite odious.

Fortunately, vim also has a setting called 'expandtab', which changes all literal tab characters into the equivalent number of spaces (depending, of course, on what your tabstop is).

Shiftwidth is a setting that allows you to shift lines of text (in- or outdent) by a certain number of spaces.

In vim, I never actually use the tab key. I use a shift operation to do all my non-automatic indenting.

Quote:
Why would you want your tabs set to 8?

Using your favourite language, do the equivalent of the following:
Code:

---

perl -e'print "\n\t#\n        #\n";'

---

There are 8 spaces in that last part. Run that wherever you choose and let me know how often those hash marks don't line up (assuming a fixed width font, of course). Next, create a simple text file containing those two lines. Print it out on paper, again with a fixed width font. I bet the colons line up, right? Then, in a shell, cat the file (I think the old DOS command was 'type'). How big are the tabs? Throw some <pre></pre> tags around it, and view it in a webpage. I bet those hash marks line up, right? They do in Firefox, links, lynx, and konqueror.

Aside from a text-editor where someone has manually changed the tabstop to something other than 8, a tabstop is 8 spaces. If you look at the documentation of the text-editor that person is using, I'd be willing to bet that the default tabstop (which they've changed) is 8.

Where else, other than your text editor, can you change how a tabstop is displayed? I'd bet nowhere. That's because 8 spaces is the standard. Don't change what's standard.

Quote:
I usually indent everything 2 spaces and have my editor set to insert spaces instead of tabs.

This sounds like it's the equivalent of having 'expandtabs' turned on in vim.

Quote:
Of course, with the editors I use (VS.net and Delphi) the whole tab functionality is really obsolete anyway. VS.net formats your code as soon as you put your closing brace and Delphi has a "smart tab" which inserts spaces up until you reach the next character-after-a-space on the previous line (or the most recent line that extends as far as you're typing).

Yes, smartindent is great -- vim has that, as well, and I use it. It doesn't make tab functionality obsolete, however, as, if there are literal tab characters in your file when it gets saved, then they're still there regardless of how your editor displays them.

Quote:
However, on this subject, tabs in general just drive me nuts. In fact, if the editor doesn't have the option to insert spaces instead of tabs, I just ignore the tab button. I hate opening code in a different editor and having it look like garbage because the previous program used a different tab setting than the one I have now.

Now you know why you should never change the tabstop setting from 8. If you have, the only place your formatting will ever look "correct" is in the place it was originally edited.

Quote:
And on THAT subject, why is it that no one seems to ever format SQL code?

We do -- it's a department coding standard.

Quote:
Aside from a text-editor where someone has manually changed the tabstop to something other than 8, a tabstop is 8 spaces.

Quote:

Quote:
tabstop should never be set to anything other than 8.

GNU/Emacs freak.

Au contraire. The first thing I do after installing a linux distro is remove Emacs. (Historically, it was because I never used it, and when using tiny hard-drives, it took up waaaay too much space for something I never used. Now it's just a matter of principle.)

Don't mistake my advocacy of 8 space tab stops as advocacy of GNUs standard for mixing tabs and spaces. That's even worse than using non-standard tabstops, since the tabs are at least internally consistent.

Quote:

Quote:
You really should be using what vim calls 'softtabstop' (along with 'shiftwidth'), which allows you to edit as though a tabstop is 2 spaces, but leaves the tabstop definition at the standard 8 spaces.

Nope, just "tabstop=2 shiftwidth=2". Interesting idea, though.

  if (!statOnly) {

    if (result.errorCode) {

      if (result.messages.size() > 0) {

        TXT_Printf(stderr, SEV_ERROR, "%s\n", (const char *)result.messages[0]);

      }

      else

        TXT_Printf(stderr, SEV_ERROR, "Unknown error.\n");

    exit(result.errorCode);

  }

        if (!statOnly) {

                 if (result.errorCode) {

                        if (result.messages.size() > 0) {

                                TXT_Printf(stderr, SEV_ERROR, "%s\n", (const cha

r *)result.messages[0]);

                        }

                        else

                                TXT_Printf(stderr, SEV_ERROR, "Unknown error.\n"

);

                exit(result.errorCode);

        }

Quote:

Quote:
I really hope you also have 'expandtab' set (which, for the non-vim users, turns tab stops to spaces).

Nope.

See, I find it useful for indents to be one character. It helps me find matching indents better when they span a screen's worth of data.

if ( a<b ) {
  if ( c<d ) {
    if ( e<f ||
         g<h ) {
      doit();
    }
  }
}

if ( a<b ) {
ttif ( c<d ) {
ttttif ( e<f ||
ttttsssssg<h ) {
ttttttdoit();
tttt}
tt}
}

Quote:

Quote:
Aside from a text-editor where someone has manually changed the tabstop to something other than 8, a tabstop is 8 spaces.

Not true in my world, I'm afraid. VS.NET has it set to 4

Huh. I haven't used windows since... uh... NT 4.0, I think, so I'm coming to this primarily from a unix standpoint. I'm certainly not up on all the fancy IDE editors out there, particularly on Windows.

Quote:
I also just realized that vs.net indents four rather than two.

Well, at least it's a good indent. 2 space indents are too small, IMHO. I like 4 space indents.

Quote:
Anyway, I guess in my early days I ran into too many apps where tabs were not 8 spaces that I just gave up on tabs altogether.

I used to like tabs. Then I started working with other people.

Tabs just shouldn't be used for formatting code.

    ...
      else
        TXT_Printf(stderr, SEV_ERROR, "Unknown error.\n");
    exit(result.errorCode);

Quote:
... never touched a piece of code in their lives.

Quote:
Code:

---

    ...
      else
        TXT_Printf(stderr, SEV_ERROR, "Unknown error.\n");
    exit(result.errorCode);

---

Tsk, always brace, could be a macro!

#define TXT_Printf(X,Y...) do { stmt; stmt; stmt; } while (0)

Quote:
Shouldn't matter

Quote:
Don't make me get religious on your ass now!

LOL!

FWIW, I'm an "always put the braces" guy, but I'm not "religious" about it toward other programmers.

Quote:
Shouldn't matter, if the macro writer knew what they were doing.