Comment On Self-Documenting Comments

FIRST!

I just hope that is automatically generated code. Although I don't think computers can be that stupid by themselves.

Alex Papadimoulis:

In yesterday's post (Doing What You Say, Saying What You Do),
we all learned how important it is to be explicit when naming
functions; preferably, one should encapsulate the entire function's
logic into that function's name. Although I didn't cover commenting in
yesterday's post, the same rule should apply: be as explicit as
possible. The ideal comments are free of any non-programming languages
(English, Dutch, etc) and should be as verbatim to the code as
possible. Nick F demonstrates this perfectly with code from
(what I would imagine is) the
set_actionType_to_cont_or_end_depending_on_whether_hasSiblings_is_true_or_false()
function ...

// if hasSiblings, actionType == cont; else actionType == end.

if ($hasSiblings)
{
  $actionType = "cont";
} 
else 
{
  $actionType = "end";
}

Not really related to the WTF at all, but something I've been
wondering:  Am I the only one who likes the ternary ?:
operator?  It is usually grouped with global variables and goto
statements as "bad no matter what."



$actionType = $hasSiblings ? "cont" : "end";



That is much easier and doesn't waste so much space, and I don't see how it would be hard to understand...

Anonymous:

FIRST!

"Yay, I got mail!"

const int CONSTANT_WITH_VALUE_ZERO = (int)0;
const int CONSTANT_WITH_VALUE_ONE_GREATER_THAN_ZERO = (int)1 + (int)CONSTANT_WITH_VALUE_ZERO;

// if_verbosity == tedious then exit_program else exit_program_scarcastically
if_if_verbosity_is_tedious_exit_program_else_exit_program_scarcastically( bool true_or_false_value_of_verbosity )
{
    if( true_or_false_value_of_verbosity == true )
    {
  exit_program_and_stop_executing_program_and_return_control_to_operating_system_____tech_savvy_people_might_call_it_an_os_comma_you _should_be_aware_of_that_fact( CONSTANT_WITH_VALUE_ZERO );
    }
    else
    {
    std::cout << "Ha! That's right, verbosity isn't tedious!" << std::endl;
exit_program_and_stop_executing_program_and_return_control_to_operating_system_____tech_savvy_people_might_call_it_an_os_comma_you
_should_be_aware_of_that_fact( CONSTANT_WITH_VALUE_ONE_GREATER_THAN_ZERO );

    }
}

Oh, I hope this formats!

kipthegreat:

Not really related to the WTF at all, but something I've been
wondering:  Am I the only one who likes the ternary ?:
operator?  It is usually grouped with global variables and goto
statements as "bad no matter what."



$actionType = $hasSiblings ? "cont" : "end";



That is much easier and doesn't waste so much space, and I don't see how it would be hard to understand...

Nope, I have had a love affair with the ternary for quite some time.

The ternary operator is a beautiful thing. Heck, it even has a cool name.

WTFer:

I just hope that is automatically generated code.
Although I don't think computers can be that stupid by themselves.

I wish.  Here's a small snippet from a project I got sucked into.  Every line of code is commented like this.



    ' Instantiate the file system object

    Set lfsoFileSystem = CreateObject(FILE_SYSTEM)

   

    If lfsoFileSystem.FileExists(rstrFile) Then

        ' Retrieve the file

        Set lfilFile = lfsoFileSystem.GetFile(rstrFile)

        ' Open the file as a stream

        Set mtsActiveStream = lfilFile.OpenAsTextStream(rlngMode)

        ' Hold the file

        Set mfilActiveFile = lfilFile

        ' Release the file

        Set lfilFile = Nothing

        ' Hold that the operation was successful

        llngSuccess = SUCCESS

    Else

tertiary is not neccissarily bad.  I use it in lots of situations,
but not generally for the case you site.  I use it whenever I'm
doing the same thing with a slightly different parameter.  ie:



function_call( var1, var2, is_blah() ? varX : varY);



instead of:



if(is_blah())

  function_call(var1, var2, varX);

else

  function_call(var1, var2, varY);

Anonymous:

FIRST!

TENTH!!!



Seriously, we need to implement something similar to Fark.com, someone
that posts "First Post!" gets the text of their comment changed to
"Boobies!" and the time stamp on it changes to 12 hours into the future.

kipthegreat:

Not really related to the WTF at all, but something I've been
wondering:  Am I the only one who likes the ternary ?:
operator?  It is usually grouped with global variables and goto
statements as "bad no matter what."



$actionType = $hasSiblings ? "cont" : "end";



That is much easier and doesn't waste so much space, and I don't see how it would be hard to understand...

Really?  I hadn't ever heard that the ternary operator is bad
practice.  I wonder what the justification for that blanket
statement is?  Anyone know?



I know it was confusing the first time I saw one, but once I figured it out I was like "Neato!" and "First Post!!!!1111".

Meh, when I write pseudocode like that and go back later to make it into real code. I often leave the comments.

New programmers are often warned against using the ternary operator because they often don't get it - they think of it as a shortcut for 'if', not as an operator returning a value. Also, it does have some potential for obfuscation if used carelessly - but then, what doesn't?

Needless to say, I like it myself, but I try to be careful where and when I use it.

kipthegreat:

$actionType = $hasSiblings ? "cont" : "end";



That is much easier and doesn't waste so much space, and I don't see how it would be hard to understand...

You forgot the comment:

//$actionType = $hasSiblings ? "cont" : "end";

$actionType = $hasSiblings ? "cont" : "end";

Anonymous:

Meh, when I write pseudocode like that and go
back later to make it into real code. I often leave the
comments.

You need to get one of those "The Cheat" pictures as your avatar.

Oh, come on. Get off your lazy asses and type an if/then/else like a normal human being. No one wants to maintain an if block that's all smashed together on one line just because you thought it was 'leet.

 

Alex Papadimoulis:

In yesterday's post (Doing What You Say, Saying What You Do),
we all learned how important it is to be explicit when naming
functions; preferably, one should encapsulate the entire function's
logic into that function's name. Although I didn't cover commenting in
yesterday's post, the same rule should apply: be as explicit as
possible. The ideal comments are free of any non-programming languages
(English, Dutch, etc) and should be as verbatim to the code as
possible. Nick F demonstrates this perfectly with code from
(what I would imagine is) the
set_actionType_to_cont_or_end_depending_on_whether_hasSiblings_is_true_or_false()
function ...

// if hasSiblings, actionType == cont; else actionType == end.

if ($hasSiblings)
{
  $actionType = "cont";
} 
else 
{
  $actionType = "end";
}

So what is so bad about this? Granted, the comment does nothing to
explain what the coding is doing but it's no worse than people who do
not write any comments at all. The comments in the code can be pretty
funny or strange at times but it's a little bit of stretch to spend an
entire post making fun of one useless comment.

This programmer probably has some interesting code. Couldn't the submitter have found something funnier than this?



- Dan

kipthegreat:

Not really related to the WTF at all, but something I've been
wondering:  Am I the only one who likes the ternary ?:
operator?  It is usually grouped with global variables and goto
statements as "bad no matter what."



$actionType = $hasSiblings ? "cont" : "end";



That is much easier and doesn't waste so much space, and I don't see how it would be hard to understand...

There is nothing bad about it. It is really a matter of taste. I happen
not to like it. I imagine it would be more difficult for me to follow
than the standard if statement once it gets to be a nested if.



- Dan

Not really a WTF at all...just kind of stupid and pointless.

Oh, and I like ternary for squishing an if statement all on one line.

kipthegreat:

Alex Papadimoulis:

In yesterday's post (Doing What You Say, Saying What You Do), we all learned how important it is to be explicit when naming functions; preferably, one should encapsulate the entire function's logic into that function's name. Although I didn't cover commenting in yesterday's post, the same rule should apply: be as explicit as possible. The ideal comments are free of any non-programming languages (English, Dutch, etc) and should be as verbatim to the code as possible. Nick F demonstrates this perfectly with code from (what I would imagine is) the set_actionType_to_cont_or_end_depending_on_whether_hasSiblings_is_true_or_false() function ...

// if hasSiblings, actionType == cont; else actionType == end.

if ($hasSiblings)
{
  $actionType = "cont";
} 
else 
{
  $actionType = "end";
}

Not really related to the WTF at all, but something I've been wondering:  Am I the only one who likes the ternary ?: operator?  It is usually grouped with global variables and goto statements as "bad no matter what."

$actionType = $hasSiblings ? "cont" : "end";

That is much easier and doesn't waste so much space, and I don't see how it would be hard to understand...

I haven't tried the ternary operator this way in C-based languages, but in VB it's dangerous. You can use the IIf( ) function, which truly is a function and not an operator.

answer = IIf(condition, truepart, falsepart)

If you put function names in the truepart and falsepart, it will execute both functions regardless of the condition, and then try to take the return value of the appropriate one and apply it to "answer". So don't think that it's a direct replacement for:

If condition
 answer = truepart
Else
 answer = falsepart
End If

Turnary operators can be pretty useful though.

printf("There is %d %s of foo\n", cnt, ((cnt == 1) ? "instance" : "instances"));

Without:

if (cnt==1)

   printf("There is 1 instance of foo\n");

else

   printf("There is %d instances of foo\n", cnt);

 

Is that really that unmaintainable?

I'm suprised nobody has pointed out the syntax error in the comments
themselves...it's using the boolean operator "==" rather then the
assignment one...the comment SHOULD be:



//if hasSiblings actionType = cont, else ActionType = end.



I also removed the extra "," have hasSiblings and the obviously
incorrect semi-colon.  Don't you know your comments have to
compile!?



(Note:  I do realize that they may have used the boolean operator
on purpose (as in "then actionType == cont is true"), if this is the
case it's obviously someone being silly, or strung out on a caffeine
binge)

kipthegreat:

Alex Papadimoulis:

In yesterday's post (Doing What You Say, Saying What You Do),
we all learned how important it is to be explicit when naming
functions; preferably, one should encapsulate the entire function's
logic into that function's name. Although I didn't cover commenting in
yesterday's post, the same rule should apply: be as explicit as
possible. The ideal comments are free of any non-programming languages
(English, Dutch, etc) and should be as verbatim to the code as
possible. Nick F demonstrates this perfectly with code from
(what I would imagine is) the
set_actionType_to_cont_or_end_depending_on_whether_hasSiblings_is_true_or_false()
function ...

// if hasSiblings, actionType == cont; else actionType == end.

if ($hasSiblings)
{
  $actionType = "cont";
} 
else 
{
  $actionType = "end";
}

Not really related to the WTF at all, but something I've been
wondering:  Am I the only one who likes the ternary ?:
operator?  It is usually grouped with global variables and goto
statements as "bad no matter what."



$actionType = $hasSiblings ? "cont" : "end";



That is much easier and doesn't waste so much space, and I don't see how it would be hard to understand...

I usually try and stay away from it because people who come along later
always make the same grunting puzzled sound when they see it
"Uhhaarooo?" and I have to explain it's just another way of writing a
conditional, but the little crease between their eyebrows never goes
away, and I know as soon as I'm not looking, that line will be replaced
with if-then-else.



So I just save a step, and leave it out.

terniary operator's rule.



 I specially like them nested

at least 5 deep.



 buy hey, howcome this code is here?

 is wtf out of code?

 I have some real wtfery I could post.

 cause this is boring.



lets get some stuff with some meat up in here..

 I want something to REALLY laugh about.

 

 its good bonding for the team when we all gather around one station and poke fun at the code provided here.



 but this is just no fun at all.



 bool flag = value?(value>1?(value>2?(value>3?(value>4?(value>5?true:false):false):true):false):true):false;



... lol something like that anyhow.

That's exactly what I was thinking.  Ternary.  :)  This
whole function is not even necessary.  just turn the function name
into a comment, and turn the underscores into spaces.  If you even
need to do that much.



JC

Ytram:

Anonymous:

FIRST!

TENTH!!!



Seriously, we need to implement something similar to Fark.com, someone
that posts "First Post!" gets the text of their comment changed to
"Boobies!" and the time stamp on it changes to 12 hours into the future.

It'd be hard to enforce...people start typing other things to get past the filter.



The real reason Fark doesn't have the FP moron crowd is because the
TFers always get the first ten posts, and they pay for it, and thus
feel no need to grandstand.

Boobies!

I'm always skeptical when I see a variable named like "actionType" and it's a string. Later on down in the code there's probably a line that says "if ($actionType == 'cont')". Yeesh. In cases like this, I'm inclined to use.. I dunno, enumerated values? Constants (defined as integers maybe?) Something with which I can minimize case-sensitive string errors n' such. Should we get into a discussion about the time difference it takes to compare two integers versus two strings? Nah, I don't want to be one of THOSE types of post whores.

Anonymous:

terniary operator's rule.



 I specially like them nested

at least 5 deep.



 buy hey, howcome this code is here?

 is wtf out of code?

 I have some real wtfery I could post.

 cause this is boring.



lets get some stuff with some meat up in here..

 I want something to REALLY laugh about.

 

 its good bonding for the team when we all gather around one station and poke fun at the code provided here.



 but this is just no fun at all.



 bool flag = value?(value>1?(value>2?(value>3?(value>4?(value>5?true:false):false):true):false):true):false;



... lol something like that anyhow.

Usually if they're kinda hard to read I'll break the two conditions out onto two lines, with : under ?, like this-



return  some_condition ? a_kinda_long_statement_might_go_here

                      
: another_sorta_long_statement_maybe;

Satanicpuppy:

Ytram:

Anonymous:

FIRST!

TENTH!!!



Seriously, we need to implement something similar to Fark.com, someone
that posts "First Post!" gets the text of their comment changed to
"Boobies!" and the time stamp on it changes to 12 hours into the future.

It'd be hard to enforce...people start typing other things to get past the filter.



The real reason Fark doesn't have the FP moron crowd is because the
TFers always get the first ten posts, and they pay for it, and thus
feel no need to grandstand.

I'm surprised no one has gotten (or commented on) the Crank Yankers
"Special Ed" reference.  I figured it was more politically correct
than just calling the first poster a retard.

Mung Kee:

"Yay, I got mail!"

Ternary is indeed a wonderful thing (although there is a special corner of hell for people who nest ternary ops), but one thing that I have seen bite the unwary is order of operations.  For example, in C++:

std::cout << 1 ? 2 : 3 ;

will output "1"!  Order of operations means that the << operator will be evaluated before the ?:, so this is the same as saying:

(std::cout << 1) ? 2 : 3 ;

Counterintuitive at best...

kipthegreat:

Not really related to the WTF at all, but something I've been
wondering:  Am I the only one who likes the ternary ?:
operator?  It is usually grouped with global variables and goto
statements as "bad no matter what."



$actionType = $hasSiblings ? "cont" : "end";



That is much easier and doesn't waste so much space, and I don't see how it would be hard to understand...

I use it all the time if the elements in it aren't too long. Great stuff.

Ytram:

Anonymous:

FIRST!

TENTH!!!



Seriously, we need to implement something similar to Fark.com, someone
that posts "First Post!" gets the text of their comment changed to
"Boobies!" and the time stamp on it changes to 12 hours into the future.

Except, with this forum software, the text would get changed to



[thsetiugaggib] ddbvg  jzhfdgkuasdhg

zdsfkgkjb lbzsddfgsdrhf
Boobidghjsrthdfsh&&esrysjfysj[/thsetiugaggib]qqoxcvnlnjllttg h
llzflgklu

and the timestamp would be changed to 1 month in the past, if the first
poster used the word first -anywhere- in his/her post and happened to
be using Firefox.

A Wizard A True Star:

Oh, come on. Get off your lazy
asses and type an if/then/else like a normal human being. No one wants
to maintain an if block that's all smashed together on one line
just because you thought it was 'leet.

 

Oh, come on. Get off your lazy ass and learn to maintain real code. Sheesh.

Anonymous:

Turnary operators can be pretty useful though.

printf("There is %d %s of foo\n", cnt, ((cnt == 1) ? "instance" : "instances"));

Without:

if (cnt==1)

   printf("There is 1 instance of foo\n");

else

   printf("There is %d instances of foo\n", cnt);

 

Is that really that unmaintainable?

I'd factor everything out that can be factored out, though, like so:

printf("There is %d instance%s of foo\n", cnt, ((cnt == 1) ? "" : "s"));

What's with the mutilation of the spelling of "ternary". 



turnary

terniary

Chained ternary ops aren't so bad as long as their done correctly. The example above is perfectly readable if rewritten as:

bool flag = ( !value ? false :

              value<=1 ? true :

              value<=2 ? false :

              value<=3 ? true :

              value<=4 ? false :

              value>5 );

It's just like how most programmers wouldn't chain if statements together in the then clause (if-if-if-if-else-else-else-else), but instead would do it in the else clause to make it if-else if-else if-else if-else, etc.

Sheesh. Haven't you people ever done anything in functional languages?

rogthefrog:

Anonymous:

Turnary operators can be pretty useful though.

printf("There is %d %s of foo\n", cnt, ((cnt == 1) ? "instance" : "instances"));

Without:

if (cnt==1)

   printf("There is 1 instance of foo\n");

else

   printf("There is %d instances of foo\n", cnt);

 

Is that really that unmaintainable?

I'd factor everything out that can be factored out, though, like so:

printf("There is %d instance%s of foo\n", cnt, ((cnt == 1) ? "" : "s"));

Actually, if we're going down that road:

printf("There %s %d instance%s of foo\n", (cnt == 1 ? "is" : "are"), cnt, (cnt == 1 ? "" : "s"));

Which means we're better off with an if statement here. Oh well.

rogthefrog:

I'd factor everything out that can be factored out, though, like so: printf("There is %d instance%s of foo\n", cnt, ((cnt == 1) ? "" : "s"));

I'm not an english-speaking person, but.. wouldn't it be: "there ARE %d instanceS of foo\n", for cnt>1 ?

Sigh.  That was supposed to be:





bool flag = ( !value ? false :


              value<=1 ? true :


              value<=2 ? false :


              value<=3 ? true :


              value<=4 ? false :


              value>5 );



I hate this forum software.

Surely that should be

printf("There %s %d instance%s of foo\n", ((cnt == 1) ? "is" : "are"), cnt, ((cnt == 1) ? "" : "s"));

Darn, looks like I got beaten on that correction.

Which means we're better off with an if statement here. Oh well.

Why? I still like the the ? better. I'd rather keep it as one statement to visually scan over instead of an if.

Another thing: there are things you can't do without the ternary operator in some languages (like, say, C++):



   const int someVar = someCondition ? value1 : value2;



Try and do that using ifs.  Maybe with some truly wretched casting
it would be possible, but at that point, you're very clearly much better off just using the ternary operator.

Anonymous:

Which means we're better off with an if statement here. Oh well.

Why? I still like the the ? better. I'd rather keep it as one statement to visually scan over instead of an if.

I'd venture to guess the reason is because with an if statement, you
don't have to do "cnt == 1" twice.  I've no idea if that'd make
any difference in anything whatsoever, but it seems a wee bit silly to
do two comparisons when you could get away with just one.

Anonymous:

Surely that should be
printf("There %s %d instance%s of foo\n", ((cnt == 1) ? "is" : "are"), cnt, ((cnt == 1) ? "" : "s"));

oh, how rotten.  baby, please.  let's refactor these puppies:

const char *get_conjugation(const char *verb, unsigned int count) ;

const char *get_plural_suffix(const char *noun, unsigned int count) ;

the implementation is left as an exercise to the reader.

emptyset:

Anonymous:

Surely that should be
printf("There %s %d instance%s of foo\n", ((cnt == 1) ? "is" : "are"), cnt, ((cnt == 1) ? "" : "s"));

oh, how rotten.  baby, please.  let's refactor these puppies:

const char *get_conjugation(const char *verb, unsigned int count) ;

const char *get_plural_suffix(const char *noun, unsigned int count) ;

the implementation is left as an exercise to the reader.

I'm sick of you and your homework.

Anonymous:

Which means we're better off with an if statement here. Oh well.

Why? I still like the the ? better. I'd rather keep it as one statement to visually scan over instead of an if.

Agreed.  You use and understand ? ? You are probably skilled and
efficient : You are a novice programmer or have to show your code to
novices.

Anonymous:

Another thing: there are things you can't do without the ternary operator in some languages (like, say, C++):



   const int someVar = someCondition ? value1 : value2;



Try and do that using ifs.  Maybe with some truly wretched casting
it would be possible, but at that point, you're very clearly much better off just using the ternary operator.

int tempVar = 0;

if (someCondition) { tempVar = value1; } else { tempVar = value2; }

const int someVar = tempVar;

I'd venture to guess the reason is because with an if statement, you don't have to do "cnt == 1" twice. I've no idea if that'd make any difference in anything whatsoever, but it seems a wee bit silly to do two comparisons when you could get away with just one.

Have you ever looked at the code needed to implement printf? A double comparison of integers is the least of your worries.

Not to mention we are either talking file IO (glaciers move faster), or interactive (the user will never notice the 2 processor cycles you saved)