Do comments annoy anyone?

[mikeblas]

In SQL Server, using the prefix sp_ suggests that the procedure is a system stored procedure. This causes SQL Server to look at the master database before checking the current database. Metadata queries are really fast, but this does put a tiny bit of overhead into the resolution and execution of the procedure.

I can't figure out what's redundant about using "Tbl" for a table name, though it's a practice I don't exercise.

 

[ameoba]

It's a database. It's good at looking things up. Probably far better than I am at reading through ridiculously verbose names.

 

[Cyrilix]

I guess I should probably read up on the entire "spec" of Hungarian notation, but I always thought it was stuff like m_varName, to indicate that varName is a class member variable and not a local variable in the current scope, as well as things like g_globalVar, s_staticVar, etc.

For the record, I do the above.

 

[jmackay]

Well since this thread derailed and we are now talking about variables.. I use the following for my sql databases:

(Table):
site_longdesc_dsc (dsc = 3 letters describing the long description)
dsc_id, dsc_name, dsc_etc...

That way I know exactly what table I am grabbing variables from no matter where I'm looking in the code.

 

[ameoba]

if you're using Oracle, this will bite you. Oracle, in all its Enterprise Grade glory, limits you to 30 character identifiers.

 

[mikeblas]

Still only 30 characters? Seriously? I thought they had fixed that.

 

[svet-am]

I guess I should probably read up on the entire "spec" of Hungarian notation, but I always thought it was stuff like m_varName, to indicate that varName is a class member variable and not a local variable in the current scope, as well as things like g_globalVar, s_staticVar, etc.

For the record, I do the above.

You're thinking of Microsoft's bastardized version of Hungarian Notation. Hungarian Notation, in its simplest form, is just a guideline that dicates that you embed typing OR functional information into variable names. in non-typed languages (PHP mostly for me), I embed the usable type of the variable. In strongly typed languages (C, C++, Java), I simply embed a shorthand functional description.

 

[mikeblas]

You're thinking of Microsoft's bastardized version of Hungarian Notation.

Bastardized? A Microsoft researcher (Charles Simonyi, by name) invented it.

 

[rayman2k2]

What I really hate is this:

public class something {

/** This is the default constructor for the something class
/** It sets the current object's that variable to 1.
   public something() {
       this.that = 1;
   }
}

Yeah, no shit...

 

[svet-am]

Bastardized? A Microsoft researcher (Charles Simonyi, by name) invented it.

You are correct. But, have you read his outline on how he INTENDED it to be used? It's much different from how you see it used in practice for MFC/Win32, et al.

 

[mikeblas]

Yes, I have. In fact, I worked with Simonyi directly on a couple of projects during my tenure on the Visual C++ team as the MFC development lead. What you're abrasively and inappropriately calling a "bastardization" is really a very natural migration of Simonyi's original proposal. In a library like MFC or an API like Win32, a variable often has no more context than its type, and the application of the variable is either unknown or too amorphous to encapsulate in its name.

 

[DrFreeze]

ive been working on a web app in java for the past months (got put on a project which was already running), and i find myself hardly commenting at all, if i ever use comment slashes it is usually to signal a TODO in the code.

The thing is, this web-app is structured quite well, and most of the stuff is kind of self explanatory once you get the hang of the structure.

The annoying thing is that the other guy working on it hardly commented as well, since he was the only guy working on the code anyway, but when i got brought in, it took me a while to entirely understand the whole thing

oddly though, he does sometimes leaves ultra-flipping obvious comments in his code like:

if (isEmpty(errorMessages)){
    //no errors, input correct
    *code*
} else {
   // errors, input not correct
   *code*
}

which tends to annoy me sometimes, sometimes he even adds logging statements after the comment, like triple redundancy...

in all fairness though, having a good IDE can really cut back on the need to explain stuff, Netbeans allows clicking on a method call so you go directly to the sourcecode of that method etc..

 

[mikeblas]

How are comments redundant to logging? What language is it that you're using?

 

[eeyrjmr]

I hate that kind of commenting. Instead of clarifying the code, it makes it redundant and difficult for me to read. Here's some string parsing code I've had to maintain, written by a developer that obviously never heard of strtok():

      if (((*p == ' ') ||                // if space char, or
           (*p == '-') ||                // hyphen char, or
           (*p == '_'))                  // underscore char
           && (isalnum(*(p+1))))         // and next char is alphanumeric
      {
         p++;                            // advance forward one char in string
         while (isalnum(*p))             // while char is alphanumeric
            p++;                         // advance forward one char in string
         if (((*p == ' ') ||             // if space char, or
              (*p == '-') ||             // hyphen char, or
              (*p == '_'))               // underscore char
              && (isalnum(*(p+1))))      // and next char is alphanumeric
         {
            p++;                         // advance forward one char in string
            while (isalnum(*p))          // while char is alphanumeric
               p++;                      // advance forward one char in string
            if (((*p == ' ') ||          // if space char, or
                 (*p == '-') ||          // hyphen char, or
                 (*p == '_'))            // underscore char
                 && (isalnum(*(p+1))))   // and next char is alphanumeric
            {
               p++;                      // advance forward one char in string
               while (isalnum(*p))       // while char is alphanumeric
                  p++;                   // advance forward one char in string
            }
         }
      }

UGH!

You don't code in assembler do you
only way you can EVER follow assember (even 5min later) is to comment EVERY line to say what is ment to be in that reg at that time or what that shift should do

 

[eggrock]

QFT.

This attitude usually changes when the developer starts doing modifications to unfamiliar code that was written by the same mindset.

Maintaining code *without* comments really, really pisses me off. I see a lot of Korn files... that source other files... that expect certain environment variables to be set.

Before you know it, 200 lines of code in a simple script is taking all goddamned day to figure out. So I tough it out once and comment it (rarely) or convert it to Perl (likely) and comment the hell out of it. Not "prints output to screen" but what the program does, when and what changes were made, what subroutines expect and return and so on.

From the looks of things not very many shell coders like to comment their, or even name their variables in some obvious format. I write enough Perl that I can't go back in six months and remember exactly what I was doing (or why, sometimes,) so I nearly always comment my stuff. The only time I don't is if I don't expect to reuse it much. That makes it easy to look for uncommented code and delete it later.

[edit] And I think naming variables 'correctly' is in essence commenting your code. Always good to follow, whatever system you use.

 

[doh]

You don't code in assembler do you
only way you can EVER follow assember (even 5min later) is to comment EVERY line to say what is ment to be in that reg at that time or what that shift should do

So true.

 

[mikeblas]

So true.

Is it? Since assembler is so minute, I generally find the idioms stand out pretty quickly. And any serious assembly work (that is, large files) involves macros to further encapsulate functional groups.

It's hard for me to think tautological comments help in any language, even assembler:

 

[CEpeep]

At my new job, I work on a codebase shared by more than a dozen people. Most of my comments are for things I change because someone else broke them. I don't comment on most new code, because the SVN log keeps track of who did what and why.

 

[doh]

Is it? Since assembler is so minute, I generally find the idioms stand out pretty quickly. And any serious assembly work (that is, large files) involves macros to further encapsulate functional groups.

It's hard for me to think tautological comments help in any language, even assembler:

Unless you and everyone who has to look at the code has done assembly for a very long time then I think comments are essential. It's easy to look at LDAA #$80 and say it's loading 0x80 into the A accumulator but what does it mean? Why was it done? What is its affect twenty lines down?

 

[mikeblas]

Unless you and everyone who has to look at the code has done assembly for a very long time then I think comments are essential. It's easy to look at LDAA #$80 and say it's loading 0x80 into the A accumulator but what does it mean? Why was it done? What is its affect twenty lines down?

Sure; but this kind of commenting is good in any language. The comments that eeyrjmr quoted when he brought up assembly were very self-evident. I don't think those help in any language, and as you point out, they're certainly no help in assembly.

 

[eeyrjmr]

Well I wasn't talking abt doing

mov ax, bx    ;we move ax into bx
add ax, bx    ;add the contents of bx into ax

since that is self-evident

HOWEVER...

mov ax, 0200h

thats nice... so you have put 0x0200 into the ax register...
whats that suppose todo?

no comment... no chance
every line really needs a comment

 

[mikeblas]

Well I wasn't talking abt doing

I see -- thing is, that's exactly what the code you quoted was doing back in post #. Thanks for the clarification!

thats nice... so you have put 0x0200 into the ax register...
whats that suppose todo?

In practice, a single line of assembly isn't enough context. I'm still not sure I'd agree that a comment is necessary on every line, since the subsequent lines usually make it obvious why something was done. In this example,

mov ax, 0200h
add sMatchScore, ax  ; add 512 to match score

it should be pretty obvious what the mov line does. And the surrounding lines will include information on why this code path was, or was not taken:

mov bl, byte ptr [si]       ; get next byte from the string
inc si
cmp bl, MATCH_MARKER ; if it is it a match marker, a match is more likely for the packet
jne NotMatched
mov ax, 0200h 
add dwMatchScore, ax  ; so we'll add 512 to match score
NotMatched:

That is, since the language is so sparse for functionality, I don't think a comment per line is as strictly necessary as you're suggesting.

 

[osalcido]

I just wish there was an easy way to hide code comments in Visual Studio .NET

It's not like I need them all the damn time....

Anyone know any?

 

[MadJuggla9]

I just wish there was an easy way to hide code comments in Visual Studio .NET

It's not like I need them all the damn time....

Anyone know any?

How does this relate? Anywho, if you don't have the ability to expand/contract code blocks try using /* and */ or a different editor if that doesn't work.

I look at it as take them or leave them. There really isn't a use in writing the comments if you know whats going on or don't want them there in the first place. I've never developed a .NET app that the editor did not have the expand/contract option for comments in this fashion:

/* begin
-----
end */

 

[bassman]

You don't code in assembler do you
only way you can EVER follow assember (even 5min later) is to comment EVERY line to say what is ment to be in that reg at that time or what that shift should do

I have done x86 and 68k assembler before, but I my current job doesn't require it. Even when I used it, I didn't find it necessary to comment every line.

That's beside the point - the code I provided isn't assembler. It's C. The comments add nothing.

 

[DrFreeze]

How are comments redundant to logging? What language is it that you're using?

this is all in java

as for comments redundant to logging, if you take the following:

if (!isEmpty(errorMessages)) {
   // error ocurred
   logger.log("an error ocurred in code XXX");
   *handle error*
}

then by reading the logging statement, you can pretty much figure out what is going on, if the IF condition wasnt descriptive enough (which most of the time they are), then you can simply read the logging statement (yeah for code highlighting) to see what is going on

granted it might be a bit of a weak argument, but i tend to lean in favor of sparse comments and only if absolutely needed, and this sort of stuff kind of annoyes me sometimes

 

[mikeblas]

I think the reason you find the comment annoying is not because comments are redundant to logging; it's because the comment you've shown is almost completely transparent.

Proper comments are certainly not redundant to logging because good comments are for the developer, while logging is for the end user. Comments can show the developer far more information than would be appropriate to show the end user in the log file.

Further, at some point in the code, logging information is dynamic and not apparent. Why does this code simply log "an error occurred in code XXX", but ignore the error message string that some other code developed?

In your example, the most important comments and code are missing. Logging the error is orthogonal to actually handling it and recovering from it, and that code certainly needs comments.

By the way, tell me: what do you mean by "annoyed"? Do you think the comment was a waste of time for someone else to write? Do you find it somehow interrupts your reading of the code? Do you end up deleting it?

 

[DrFreeze]

I think the reason you find the comment annoying is not because comments are redundant to logging; it's because the comment you've shown is almost completely transparent.

Proper comments are certainly not redundant to logging because good comments are for the developer, while logging is for the end user. Comments can show the developer far more information than would be appropriate to show the end user in the log file.

Further, at some point in the code, logging information is dynamic and not apparent. Why does this code simply log "an error occurred in code XXX", but ignore the error message string that some other code developed?

In your example, the most important comments and code are missing. Logging the error is orthogonal to actually handling it and recovering from it, and that code certainly needs comments.

By the way, tell me: what do you mean by "annoyed"? Do you think the comment was a waste of time for someone else to write? Do you find it somehow interrupts your reading of the code? Do you end up deleting it?

well, a bit more info on the app. This is a web application, so any logged information will only show up in our server logs, it wont be available to any end users at all, the logs will mainly provide debug info for us, so we in fact will be putting detailed error info into the logs

my entire point is that some comments in the code are quite unneeded and as such shouldnt be there, while higher level comments (like class or method descriptions, like javadoc) are completely missing

most of the time i leave the useless comments in the code, the other guy on the project is pretty strict about doing stuff his way, so if i can avoid an argument by not deleting stuff like "// error" then thats fine with me. If it was just me on the project, it would be gone pretty fast, or never have been there in the ffirst place

i guess i kind of think like "Code was hard to write, that means it should be hard to read"
in my thinking, the reason i like coding is because of the challenge of thinking of ingenious code, and trying to get to the bottom of other peoples code by myself

 

[jellysandwich]

my code is perfect and easy to follow, so i dont put any comments <_<

js