Do not remove following no op or script will fail

2013-01-18 Reply Admin

Evan:
(And the double-negatives has implications for coding style too -- in particular, I find it rather easier to understand Booleans that are named in the positive sense. I've worked on a code base that's essentially an emulator and contained a field called isNotHalted... and you can only see if(!isNotHalted) so many times before you want to get a bit stabby and wish it had been called isRunning. :-))

BTW I should also say that what I mean by "positive" isn't a hard and fast rule. I originally put a generic example there comparing if(success) vs if(!failed) but decided that it wasn't very convincing -- and I think it's because failed is in some sense a positive word too. (It's describing what has happened -- failure -- as opposed to what has not happened, even though what has happened is the absence of something else. :-))

The presence of "not" in a variable name (e.g. isNotHalted) is probably very close to a sufficient measure for a negatively variable name, but I don't think it's necessary either. (To be honest I don't even really like if(!container.empty()) and would prefer if(container.hasStuff()) if there were a better name for it.)

2013-01-18 Reply Admin

atk:
Sgt, please avoid double negatives. It helps communication.
Cpt, please note double negatives and engage your secondary lexical parser. It's less performant but working slightly harder to understand others helps communication.

atk, please note not avoiding sentences that seem to parse one way until near the end ("It's less performant but [it's] working slightly harder to understand others helps[parse error]"), requiring a back-up and reparse, doesn't help communication.

Steve The Cynic · 2013-01-18 Reply Admin

NotARealName:
I 'might' go back and remove the comment but it must make sense to lots of people otherwise they wouldn't be including it in their own codebases, right?

I believe it's called "freight sect". Well, something like that, anyway.

2013-01-18 Reply Admin

Aris:
Comments certainly don't tell what the code does. The code is there for this. Comments can tell why the code does something.
At least, that's how I see comments ...

HOURAY !!!!!!!

2013-01-18 Reply Admin

Ah yes, Turbo Pascal. I had a program which would only work if there was a comment in a particular place. Any comment. Which is why the program ended up containing a comment saying {If you remove this comment, the program will stop working}.

Happy days.

SirHegel77 · 2013-01-18 Reply Admin

catch(Exception ex)
{
  // Please don't crash
}

For some reason this reminds me of the fairly common (and equally effective) concept of praying among human beings.

2013-01-18 Reply Admin

Evan:
Evan:
(And the double-negatives has implications for coding style too -- in particular, I find it rather easier to understand Booleans that are named in the positive sense. I've worked on a code base that's essentially an emulator and contained a field called isNotHalted... and you can only see if(!isNotHalted) so many times before you want to get a bit stabby and wish it had been called isRunning. :-))
BTW I should also say that what I mean by "positive" isn't a hard and fast rule. I originally put a generic example there comparing if(success) vs if(!failed) but decided that it wasn't very convincing -- and I think it's because failed is in some sense a positive word too. (It's describing what has happened -- failure -- as opposed to what has not happened, even though what has happened is the absence of something else. :-))
The presence of "not" in a variable name (e.g. isNotHalted) is probably very close to a sufficient measure for a negatively variable name, but I don't think it's necessary either. (To be honest I don't even really like if(!container.empty()) and would prefer if(container.hasStuff()) if there were a better name for it.)

I think clarity over arbitrary rules....

I'm happy equally happy with

while(continue) or while(!finished)

HORSES FOR COURSES PEEPS!!!!

2013-01-18 Reply Admin

chubertdev:
cellocgw:
Which shortly thereafter DID happen and the resulting notification window was submitted to the Friday Photo collection on TDWTF.

It was mostly stupid stuff like this:
Try
   intRecordID = Integer.Parse(strRecordID)
Catch ex As Exception
   'this should never happen
End Try
It gets even better. The guy responsible for the code came back to the company, and I left shortly after that. I can only imagine how bad things are there now.

Catch ex As Exception
   MsgBox("This should never have happened!")
End Try

Better?

2013-01-18 Reply Admin

Aris:
I'm an agile guy :) I don't write a lot of comments, but I make sure the one I write are useful and I make sure I write comments where it's needed.
And if I was in the situation where an important markup had not to be deleted, I'd certainly comment not to delete it. In agile, you are not afraid to change code that's working to make it better. And there's no code ownership.

I tend to agree. Far to many people comment in a cargo cult fashion. No comments are better than useless, misleading, redundant or excessive comments. Comments for the sake of comments never results in good things.

Real programmers can read code well enough to not need Rosetta comments everywhere as long as function names and variable names are reasonably accurate and the code isn't too disorganised. The most important thing for a coder to be able to do is to be able to write code, good code. The ability to write comments (at all) is secondary to this.

Comments aren't totally needless though. You obviously want them for particularly complicated or obscure pieces of code, API documentation generation (as soon as your code base reaches a certain size you will need this) and for preprocessor directives.

I prefer to hardly comment code that is being created at all in many cases until later and if at all (unfortunately time is not always permitting). The later you leave it to the less over head as once you comment a method you'll have to change the comments if you change certain aspects of a method. Whether or not this is applicable depends on your development flow.

2013-01-18 Reply Admin

fjf:
atk:
Sgt, please avoid double negatives. It helps communication.
Cpt, please note double negatives and engage your secondary lexical parser. It's less performant but working slightly harder to understand others helps communication.
atk, please note not avoiding sentences that seem to parse one way until near the end ("It's less performant but [it's] working slightly harder to understand others helps[parse error]"), requiring a back-up and reparse, doesn't help communication.

lol :)

Partially right. The "it's" that you insert is implied - this is common in English, and is grammatically correct. I did, however, forget to include "and" before "helps"

:)

2013-01-18 Reply Admin

Evan:
Evan:
(And the double-negatives has implications for coding style too...isNotHalted... and you can only see if(!isNotHalted) so many times before you want to get a bit stabby and wish it had been called isRunning. :-))
BTW I should also say that what I mean by "positive" isn't a hard and fast rule. I originally put a generic example there comparing if(success) vs if(!failed) but decided that it wasn't very convincing -- and I think it's because failed is in some sense a positive word too. (It's describing what has happened -- failure -- as opposed to what has not happened, even though what has happened is the absence of something else. :-))
...

I agree. if(!(isNotRunning)) or if(!(a&&b||c&&d||a&&c)) often forces the reader to do a lot more work than the inverse.

2013-01-18 Reply Admin

explain it:
Lines such as above
"# Do not remove following no op or script will fail"

are ok, except for the explanation, which might in this case be

Because of a reproducable bug in dtksh version x.y

Exactly.

If you have to do something screwy because of a bug in something else, use comments to document what the bug is and what version the bug was found in.

I had some third-party source code which triggered a bug in a cross-compiler I was using. (The compiler generated an invalid assembly language statement!) It turned out that simply declaring the particular variable as "volatile" was enough to fix it, so I put "#if 1 / volatile / #endif" in front of the variable's declaration, with comments about which version of the compiler it happened in. (It was in fact fixed in a later version of the compiler.)

2013-01-18 Reply Admin

no laughing matter:
Wronged:
Comments should show WHY code is needed - its context in the real world, not IT speak. It should be written in a way that the business would understand.
Probability that "the business" reads the code: <0.0001
Probability that another developer reads (and tries to understand) the code: 1

Well, really now:

Probability that another developer reads the code: close to 1

Probability that another developer tries to understand the code before making changes: 0.5

2013-01-18 Reply Admin

Wronged:
Anonymous:
Wronged:
WRONG. Comments should show WHY code is needed - its context in the real world, not IT speak. It should be written in a way that the business would understand. They should be language and implementation neutral, and concise enough to be written carefully. If your code has comments saying 'add one because we've got an offset I can't figure out' then you've got a crap team. If all your team don't comment then please let us know your company so I never apply for a job there.
You should only comment code that isn't clear (and most of your code should be clear without them). You should definitely not be using business terminology in the code unless it's vital to understanding the code. The code should be logical, but the business world usually isn't. The comments are for developers, not management.

And that my friends is why software is often so poorly designed, badly written, buggy and late - because IT people think domain knowledge is 'management speak' and refuse to use it.

And very, very often, you code is not as clear as you think.

Yes, any competent programmer who reads a line of code that says, for example, "amount=price*quantity" should be able to figure out that you're multiplying the price by the quantity. If he can't figure that out, this person should not be a programmer. And MAYBE the purpose of that line is obvious in context and doesn't need a comment. But a category of very useful comments are the ones that say "Must do this before calculating sales tax" or "price is from the line_item record, not the product_master". There are all sorts of minor subtleties that may not be obvious to someone reading this six months later.

And where comments are really useful is to tell me the overal purpose of this block of code. Yes, I can hack through and see that you're adding 1 to x here and dividing by two over there. But what are you trying to accomplish? A simple comment like "Find all employees who retired in the past year and update their benefits" can save someone a lot of fumbling.

Matt Westwood · 2013-01-18 Reply Admin

herby:
On comments:
I have a simple methodology: Write the comments for YOURSELF, so YOU can understand the code. This is a reasonable task since if you are away from the code for about 6 months, you will have forgotten the minutia of how it works, why you did it, and the errors you discovered along the way. If you write the comments for your own understanding, they will be clear in your mind, and the side effect of this is that they will most likely be clear to others as well.

Really, a simple philosophy.

What usually happens is that 6 months after writing a code unit (class, method, whatever), you have to do some maintenance of it, so spend several time-units working out what it did. That's when you comment what it does, so you don't have to figure it out again. You will also find those comments better than the ones you would have written when you initially wrote the code.

Matt Westwood · 2013-01-18 Reply Admin

Dan Mercer:
Way back in the 90's I wrote a simple toolbar app in HP's dtksh (a Korn Shell ksh93 with extensions for the common desktop environment). We had a standard tool for launching our apps but that required a full X11 environment, which our users found intrusive, as opposed to my app which launched each app as if it was hosted directly under Windows. So, of course our user base saw it and decided to switch to it. 400 users using a quick and dirty app designed for one person's personal use. The problem - there was a bug in dtksh that caused it to crash. When I put in print statements to capture data, it wouldn't crash. Finally i put in a line with
:

which is a no op that returns true. And of course I had to precede it with:

Do not remove following no op or script will fail

Should also have explained "This oddity is caused by a bug in dtksh which causes it to crash if there are no print statements in it to capture data."

2013-01-18 Reply Admin

BTW, my absolute favorite comments are those that state the obvious. Like not long ago I came across this line:

x=x+y; // add y to x

Well, wow, thanks for that comment. Yeah, I forgot what "+" means in Java.

It would have been nicer still if you'd told me what "x" and "y" are, though. If you're going to give your variables meaningless names, AND you're going to write comments, maybe you could use the comments to tell me what the variables are instead of giving me a tutorial on Java.

2013-01-18 Reply Admin

dpm:
Beginners comment nothing. Apprentices comment the obvious. Journeymen comment the reason for doing it. Masters comment the reason for not doing it another way. -- Richard C. Haven

Excellent point. I recently wrote some code that seemed like the simple and obvious way to get the job done, but it didn't work because of some subtleties. So I figured out how to do it in a more complex way that did work. But it occurred to me that someone coming along later might say, "This is stupid, why don't you just ...", and then delete the working code, put in the "obvious" code, and then find out why it doesn't work and have to put it all back. So I left in the non-working code, commented it out, and put in a comment that said "This doesn't work" and a sentence about why not.

2013-01-18 Reply Admin

frankly i envy the people screaming "ALL CODE IS INHERENTLY SELF EXPLANATORY, OR IT SUCKS" because these people have obviously never had to write in WebFOCUS (hope you like GOTOs and 6-character-max variable names), or get some ajaxy thing working in a half-dozen ancient browsers because of reasons beyond the developer's control. we don't all work in paradise.

2013-01-18 Reply Admin

to elaborate: most of my comments are explaining how the following apparently-nonsensical block of code skirts around a stupid bug in the product.

2013-01-18 Reply Admin

jay:
dpm:
Beginners comment nothing. Apprentices comment the obvious. Journeymen comment the reason for doing it. Masters comment the reason for not doing it another way. -- Richard C. Haven

Excellent point. I recently wrote some code that seemed like the simple and obvious way to get the job done, but it didn't work because of some subtleties. So I figured out how to do it in a more complex way that did work. But it occurred to me that someone coming along later might say, "This is stupid, why don't you just ...", and then delete the working code, put in the "obvious" code, and then find out why it doesn't work and have to put it all back. So I left in the non-working code, commented it out, and put in a comment that said "This doesn't work" and a sentence about why not.

Never heard of automated testing?

2013-01-18 Reply Admin

anonymous:
jay:
I recently wrote some code that seemed like the simple and obvious way to get the job done, but it didn't work because of some subtleties. So I figured out how to do it in a more complex way that did work. But it occurred to me that someone coming along later might say, "This is stupid, why don't you just ...", and then delete the working code, put in the "obvious" code, and then find out why it doesn't work and have to put it all back. So I left in the non-working code, commented it out, and put in a comment that said "This doesn't work" and a sentence about why not.

Never heard of automated testing?

The two points are not mutually exclusive. A good automated testing would probably keep the person changing Jay's code from committing breaking changes -- but they'd already have wasted their time re-writing the broken version and probably a bit of time trying to figure out why the test broke before re-figuring out what Jay already knew. Jay's comment is intended to save them from wasting their time in the first place.

[I'm not saying that Jay's approach is the only way to do things. You could write up a quick summary of the broken approach instead of leaving the code, and put in a pointer to the test. Or if you co-locate the code of the thing under test with the actual test you could reduce things further, but I don't do that and I get the impression that my way is more common.]

PiisAWheeL · 2013-01-18 Reply Admin

I write the comments first. It helps me map out what I want to do, and then I write the code to fit, adjusting the comments as necessary.

da Doctah · 2013-01-18 Reply Admin

Zylon:
da Doctah:
Best comment I was ever responsible for had to do with branching to two different decode routines depending on what type of terminal (and hence what format) a message had come from.
I take it we're just supposed to use the power of our imagination here.

You can use the power of a shoehorn for all it matters to me.

2013-01-20 Reply Admin

Auction_God:
Comments show where the bugs in the code are: The developer thought that it was difficult enough to require an explanation and therefore this is where they most likely made a mistake!

The semi-famous Unix v6 comment "You are not expected to understand this" which comes after some explanation is a good example. Dennis Ritchie ( http://cm.bell-labs.com/who/dmr/odd.html ) points out that that was an example where they didn't understand it, and had to rewrite the code when porting to be correct.

2013-01-20 Reply Admin

wbrianwhite:
WhiskeyJack:
Andrew:
// begin comment activity 399412
Don't you just hate it when you see this retarded shit everywhere? This is the wrong tool for the job. This is what source control history is for.

// end comment activity 399412

Sometimes I'll see, and add myself, comments like:

// Added by W.Jack, 11/11/11, Problem Report 12345 // If the mode is X, then ensure Y is set

It's also described in the version control history, as well as the problem report description, and all that good stuff, but if you're in the middle of reading/examining/editing the code, a quick 2-line note like that to remind you of some special circumstance that was taken care of, is quicker than stopping to do a diff and then firing up the reporting tools to figure out why.

Obviously we don't go overboard, and we wouldn't bother to comment silly stuff like:

// Oops, forgot to check for null pointer here

// Fixed spelling mistake

// Removed this entire function as it is no longer needed

But the major logic bugs, "don't forget to do X before Y", etc. are helpful.

Exactly. There are many devs here who ding me in code reviews saying we don't need a note about this, and we especially don't need to note the Jira number, because that's what subversion is for. Except. That I worked here before we had subversion (VSS before). I may work here after we move off of subversion (git maybe?). Same story with issue tracking tools. And nobody wants to go back through 5 years of revisions. Yes there's blame, but if someone else touches the line for an unrelated reason then someone else's change shows on that line. All that to save on the 'overhead' of 2 commented lines. I don't get it.

The better solution is to switch to a bug tracking tool that can integrate with your VCS. How often do you need to know "which bug did this code fix?" Versus "what code fixed this bug?"

2013-01-21 Reply Admin

// // Dear maintainer: // // Once you are done trying to 'optimize' this routine, // and have realized what a terrible mistake that was, // please increment the following counter as a warning // to the next guy: // // total_hours_wasted_here = 42 //

SirHegel77 · 2013-01-21 Reply Admin

Catch ex As Exception

   MsgBox("This should never have happened!")

End Try

I have to admit that I have actually done this once years ago in an ancient VB6 application. If I remember correctly, it was not even an error handler, but a select case statement with a seemingly impossible enum value. The brilliant™ piece of code was in production release for years, until one customer sent us a screenshot of a rather embarrassing message box.

2013-01-21 Reply Admin

ObiWayneKenobi:
Bad comments are worse than no comments at all, and best of all is code that is actually readable without needing a comment to explain it. Sure, maybe have a comment if the code is for a particular workflow process, but in most cases I firmly believe code should document itself by being clear and concise.

Unfortunatly I believe noone is capable of writing clear and concise code all the time. Often by external factors, most likely time-constraint. Further, it can be a huge time saver when trying to figure out a new framework or class or ... If theres some comments at the class definition you can instantly know what such an object is used for, when and why and if this class is of any use for you before reading possibly 1000+lines of code that may not even be in a language your familiar with.

2013-01-21 Reply Admin

Anonymous:
Wronged:
WRONG. Comments should show WHY code is needed - its context in the real world, not IT speak. It should be written in a way that the business would understand. They should be language and implementation neutral, and concise enough to be written carefully. If your code has comments saying 'add one because we've got an offset I can't figure out' then you've got a crap team. If all your team don't comment then please let us know your company so I never apply for a job there.
You should only comment code that isn't clear (and most of your code should be clear without them). You should definitely not be using business terminology in the code unless it's vital to understanding the code. The code should be logical, but the business world usually isn't. The comments are for developers, not management.

Wronged generally has it the wrong way around, the developers need to know how the code relates to the real world and any such comments should be targeted at them. However in this case you need to use the language of the domain the program relates to. This is necessary if you are to have an expert in the domain ensure your understanding is correct amongst other things. Ultimately you are creating a map.

2013-01-21 Reply Admin

jay:
And where comments are really useful is to tell me the overal purpose of this block of code. Yes, I can hack through and see that you're adding 1 to x here and dividing by two over there. But what are you trying to accomplish? A simple comment like "Find all employees who retired in the past year and update their benefits" can save someone a lot of fumbling.

I'd much prefer that sort of block to exist in its own well-named function (or functions). Obviously the code is hard to follow when you inline the business logic in the UI or request handlers, but if you actually move that code outside into a library where it belongs, where your functions Do One Thing And Do It Well(tm), then there's no more confusion. The higher-layers are calling lower-layer things that describe what they do and all they do, and the program itself becomes clear. You can determine whether the high-level logic is correct right then and there by reading just the code. If it is, but there's still a problem, then you can begin to work your way into the lower layers to figure out where the problem is until you find it.

What seems to happen more often than not is that developers are lazy (which BTW is never a good attribute for a programmer), and instead of taking the time to move this logic into separate modules, they just copy/paste it around and make subtle changes where necessary, and the code-base grows 3 or 10 or 100 times bigger than it needs to be. Most of the code is inlined at outer-layers and functions are hundreds of lines long.

No amount of commenting will fix this, even if you think it will. Those same lazy developers that copy-pasta are going to also neglect those comments when they change and re-arrange things.

2013-01-22 Reply Admin

Application that I stepped in to develop had some twenty forms completed, each with a help button. Every one of callback methods for the button had comment:

User wants to help

I felt very welcome there.

2013-01-22 Reply Admin

I write comments for myself, NOT for anyone else. My code is self-commenting. Even so there are times that even the best code gets too complicated (read advanced techniques). That's when I add a comment. So that I, Myself, and me won't have to spend a half-hour deciphering it again on my next visit.

There's one other type of comment I leave in languages that support it. /* Yes, I used a goddamn GOTO here. It's simpler than the mess I'd have to make by NOT using it. If you don't like it, either FO, or rewrite it and spend 4 hours every time it needs a future change. */

2013-01-23 Reply Admin

HaX0r:
Comments have many purposes (some more mundane than others). For example, I like to comment closing parenthesis. Even with an IDE that colours code and matches parenthesis, it can be difficult to work out flow in big long blocks - because little blocks become big blocks, I find commenting every parenthesis is a good habit.
Frustrating though it is, I much prefer over commented code than undercommented code eg:

/* Declare integer i */ int i;

/* Set i to 1 */ i=1;

Yes it's stupid and annoying, but I find this far easier to wade through than something with NO comments....

Sorry mate, if your code block spans over such huge blocks you are getting confused, you really need to refactor. As code evolves, comments become stale. Do you really need the overhead of having to maintain code and comments?

Consider this:

/* Declare integer i */
float a,b,c;

/* Set i to 1 */
a=42.0;

As you said yourselves: "stupid and annoying". During code maintenance, I would remove comments like this immediately. Pointless cruft cluttering the picture - causing exactly the difficulty in "working out the flow" - quoting you again.

Clearly, if someone cannot instantly parse "int i;", for what it is, then reading this code is not really theirs, is it?

2013-02-07 Reply Admin

while(!finished) is pretty clear.

while(!notCompleted) will make you stabby after a couple of times.

2016-03-23 Reply Admin

Seen this a few days ago: OpenFileDialog d = new OpenFileDialog(); d.Filter = "csv files (.csv)|.csv"; //set filter to .txt

So... either the code is lying, or the comment!

2021-10-07 Reply Admin

stromectol posologie vidal order stromectol over the counter

2021-10-08 Reply Admin

dividere pillola cialis cialis capsules

2021-10-08 Reply Admin

stromectol 3 mg tabs stromectol 3 mg uses

Comments

Do not remove following no op or script will fail

Leave a comment on “Comments”