Comment On All Talk and No Code

You know that you're really in for a treat when, after joining a large, on-going project, your technical overview consists of an email from the lead architect that reads "I have commented just about everything; you should be able to figure it out without a problem." Our anonymous poor soul who submitted this didn't quite realize how fun it would be ... [expand full text]
« PrevPage 1 | Page 2Next »

Re: All Talk and No Code

2005-12-07 05:28 • by creaothceann
52788 in reply to 52766
Personally I don't like that (ever seen ASM code with french
identifiers?), though I don't mind it in smaller programs, eg. in "Var
Datei : File;"

And my version of Paul's example would be:



falls (Bedingung)

    // irgendwas

ansonsten (Bedingung2)

    // irgendwas anderes

ende



Re: All Talk and No Code

2005-12-07 05:28 • by brazzy
52789 in reply to 52739
GoatCheez:
If the syntax of a language uses english
words, then use english ppl... it doesn't take a rocket scientist to
figure that out. Oh yeah, if you don't know english, then don't use
single letter vars... use your native language... cuz even though I
hate seeing variables named words that I could never even take a guess
to the meaning of, it's better than a variable named "v".(at least if i
need to i could probably run the variable name through a translator)





Even if you know English very well, it is often not practicable to name
everything in English. If your specifications are in a different
language, you do NOT want to translate every domain-specific term so
that the developer has to know that when the analysts and end users say
"Schuldverschreibung", he has to look in the code for "debenture".

Re: All Talk and No Code

2005-12-07 05:29 • by creaothceann
52790 in reply to 52788
*sigh*

Re: All Talk and No Code

2005-12-07 05:45 • by raph
52791 in reply to 52781

Re: All Talk and No Code

2005-12-07 06:00 • by brazzy
52792 in reply to 52750
Paul Abraham:


German example:



wenn(condition)

    // etwas

oderwenn(condition2)

    // noch etwas

Ende



I'm sure our French and German friends could do better.




I've occasionally seen this syntax for pseudocode. And it is used by spreadsheed applications for the formulas.

Re: All Talk and No Code

2005-12-07 06:11 • by brazzy
52793 in reply to 52779
Jens:
Hillarious! To bad it's not possible to use ø æ and å



A question regarding comments.



At my current place of employment we are discuraged from putting
comments in our code in general. The two exceptions to this exist rule,
is API programming and code which cannot be made self-explanatory and
therefore deserved commenting. The reason for this being that comment
are often not updated as the code evolves, thus ending up being
misleading to the maintenance programming in the end. Obviously this
approach this approach assumes that an effort is being made to keep the
implementation as clean. What are our thought on this approach to
commenting?




I generally think that comments are often over- and misused and then
more hindrance than help, but discouraging comments in general is going
a bit too far. Then again, if the exception "code that cannot be made
self-explanatory" is interpreted right, it probably covers everything
where comments are actually useful.



On second thought, I like this policy!



Jens:
Personally i'm very fond of stuff like javadoc commenting. I generally
like make a javadoc comment block for each and every
function/class/global/constant in my code, regardless of whether it's
use is self-explanatory or not.




I HATE comments that repeat things that are obvious. They are not only
useless, they actually decrease code clarity by distracting from the
code and taking up space. And the worst thing is that the same people
who comment



index++; // increase index by one



are very often those who totally fail to comment stuff that is
non-obvious and non-local, such as what a class or method is actually used for and what its name means.



Comments exist to help other people understand your code. NOT to give
you a warm, fuzzy feeling about being a good little programmer with a
high comment/code ratio.

Re: All Talk and No Code

2005-12-07 08:41 • by Jens
52798 in reply to 52793
brazzy:


I HATE comments that repeat things that are obvious. They are not only
useless, they actually decrease code clarity by distracting from the
code and taking up space. And the worst thing is that the same people
who comment



index++; // increase index by one



are very often those who totally fail to comment stuff that is
non-obvious and non-local, such as what a class or method is actually used for and what its name means.





Well I certainly agree with that.  When I said that i like to
comment stuff even though they might be self-explanatory i mean that I
like insert comment explaining the use/interface of

every function, class, global, constant, even though it's purpose might be fairly obvious, E.g.

(note, this from a



/*

*   @global array an associative array runtime configuration parameters are stored.

*/

$Configuration = array()



brazzy:


Comments exist to help other people understand your code. NOT to give
you a warm, fuzzy feeling about being a good little programmer with a
high comment/code ratio.


Damn, 'cause it's that feelin' o'rigeousness that keeps me dilligently commenting. ;-)

Re: All Talk and No Code

2005-12-07 08:49 • by kidd1270
// No comment.

Re: All Talk and No Code

2005-12-07 09:49 • by fmr
52803 in reply to 52765
That sounds like something the Quebec government
would love to invest billions into



Yeah, but only as long as they
are part of Canada, in order to prove Ottawa wastes billions sending
money to Quebec to finance such a law. If they separate, it's another
story...

Re: All Talk and No Code

2005-12-07 09:54 • by Dorfl
Aleph is about as silent as K is - sometimes, sure, but generally it isn't. I wonder if his Japanese is as bad (but not enough to actually go check it on Wikipedia).

(Actually, aleph would never be silent at the beginning of a word, but you know what I meant.)

Re: All Talk and No Code

2005-12-07 10:30 • by hank miller
I like comments like this.  



They are correct, and let me know what the mindset of the developer
was.   They are mostly useless, but it doesn't take long to
read them.   In the back of my mind I can retain the
knowledge of what 'gaiden' is, and thus every time I see that function
from then on, I know what it is doing.



The second is useful - it identifies something I don't know - what
language to translate comments from.  Without it I'd might try a
Catalin->English translator first.   (I have a soft spot
in my heart for the beautiful areas where Catalin is spoken, even though
I don't speak it myself, so I'd try that language first when I see a
Latin alphabet with a language I don't recognize.)



Where comments are not needed there should be no comments.  Where
comments are needed there should be comments.   These
comments are needed - the first explains a strange choice of names,
while the second tells me how to deal with the rest of the code.



Though I would agree with anyone who notes that both comments would be
unneeded if the rest of the code was done better in the first
place.   But given the typical code out there, comments like
this are important.

Re: All Talk and No Code

2005-12-07 11:09 • by GoatCheez
52808 in reply to 52807
System.String TextToOutput = "";
            if (CommentsNeeded)
            {
                TextToOutput += "Please Add Comments!";
                while (CommentsNeeded)
                {
                    foreach (string LineOfCode in EntireCodebase)
                    {
                        TextToOutput += "\n";
                        TextToOutput += ExplainWhy(LineOfCode);
                    }
                }
            }
            else
            {
                TextToOutput += "DO NOT ADD COMMENTS!";
            }
            System.Console.Write(TextToOutput);

Re: All Talk and No Code

2005-12-07 11:10 • by GoatCheez
52809 in reply to 52808
eh, I didn't debug my pseudo code

Re: All Talk and No Code

2005-12-07 12:14 • by RevMike
52811 in reply to 52785
ammoQ:
Jens:
Hillarious! To bad it's not possible to use ø æ and å


In Oracle's PL/SQL the can be used for identifiers, but that's a bad idea.

Just to clarify... Is it a bad idea to use those identifiers, or is PL/SQL just a bad idea in and of itself?




A question regarding comments.



At my current place of employment we are discuraged from putting
comments in our code in general. The two exceptions to this exist rule,
is API programming and code which cannot be made self-explanatory and
therefore deserved commenting. The reason for this being that comment
are often not updated as the code evolves, thus ending up being
misleading to the maintenance programming in the end. Obviously this
approach this approach assumes that an effort is being made to keep the
implementation as clean. What are our thought on this approach to
commenting?



Personally i'm very fond of stuff like javadoc commenting. I generally
like make a javadoc comment block for each and every
function/class/global/constant in my code, regardless of whether it's
use is self-explanatory or not.




Good comments do not repeat what the code already says, but why something is done. This "why" doesn't need to be updated that often.


Here here! Well spoken, Bruce!

Re: All Talk and No Code

2005-12-07 12:28 • by Gene Wirchenko
52812 in reply to 52776
java.lang.NullReferenceException:
Does D-flat have macros like good old C/C++?

// got_danish.hpp
...
#define kast throw
...
#define positiv unsigned


I see potential problems with these two.

Sincerely,

Gene Wirchenko

Re: All Talk and No Code

2005-12-07 13:11 • by sinistral
52814 in reply to 52779
Jens:
Hillarious! To bad it's not possible to use ø æ and å




Perl does support UTF-8 characters in variable names, as long as the use utf8;
pragma has been included in the source code file.  And, as someone
between your post and mine has linked to, there's the
Lingua::Romana::Perligata module for programming Perl in Latin.

Re: All Talk and No Code

2005-12-07 14:04 • by JohnO
52816 in reply to 52786

brazzy:
"Bend it like Beckham" was called "Kick it like Beckham


They must have skipped assonance and alliteration in language arts.

Re: All Talk and No Code

2005-12-07 14:24 • by ammoQ
52819 in reply to 52811
RevMike:
ammoQ:

In Oracle's PL/SQL the can be used for identifiers, but that's a bad idea.

Just to clarify... Is it a bad idea to use those identifiers, or is PL/SQL just a bad idea in and of itself?


It's definitely a bad idea to use accented letters in PL/SQL for a
simple reason: after exporting and importing them with the oracle tools
"exp" and "imp", accented letters will be replaced with their
non-accented (US7ASCII) versions. Maybe not always, but often enough.

In many cases, this alone will not immediately break the program,
because the definition of an identifier and all references are silently
changed at the same time. But it is a time bomb, because sometimes
later, you try to install a new version of the program from a script
that still contains the accented letters to install a new version and BANG it breaks at dozens of places.



About PL/SQL being "a bad idea in of itself", let's say at other database do worse (TSQL etc.)

In the company I work with, we write lots of
code in PL/SQL (read: all the business logic), and it works pretty well
for us, with typically 20-50 concurrent users, ~200 users at most.

But of course PL/SQL has its limits; I have seen projects that tried to
do things with PL/SQL it definitely was not build for, like parsing
complex templates (they made a CMS completely within

the PL/SQL cardridge of the OAS), and although it worked (kind of), it was sluggish despite all

the expensive hardware thrown at it.

Re: All Talk and No Code

2005-12-07 14:52 • by Albatross
52821 in reply to 52803

fmr:
That sounds like something the Quebec government would love to invest billions into

Yeah, but only as long as they are part of Canada, in order to prove Ottawa wastes billions sending money to Quebec to finance such a law. If they separate, it's another story...


Quebec can't separate!  If they do, Newfoundland would float away!

Re: All Talk and No Code

2005-12-07 15:00 • by RevMike
52825 in reply to 52819
ammoQ:
RevMike:
ammoQ:

In Oracle's PL/SQL the can be used for identifiers, but that's a bad idea.

Just to clarify... Is it a bad idea to use those identifiers, or is PL/SQL just a bad idea in and of itself?


It's definitely a bad idea to use accented letters in PL/SQL for a
simple reason: after exporting and importing them with the oracle tools
"exp" and "imp", accented letters will be replaced with their
non-accented (US7ASCII) versions. Maybe not always, but often enough.

In many cases, this alone will not immediately break the program,
because the definition of an identifier and all references are silently
changed at the same time. But it is a time bomb, because sometimes
later, you try to install a new version of the program from a script
that still contains the accented letters to install a new version and BANG it breaks at dozens of places.



About PL/SQL being "a bad idea in of itself", let's say at other database do worse (TSQL etc.)

In the company I work with, we write lots of
code in PL/SQL (read: all the business logic), and it works pretty well
for us, with typically 20-50 concurrent users, ~200 users at most.

But of course PL/SQL has its limits; I have seen projects that tried to
do things with PL/SQL it definitely was not build for, like parsing
complex templates (they made a CMS completely within

the PL/SQL cardridge of the OAS), and although it worked (kind of), it was sluggish despite all

the expensive hardware thrown at it.


I've actually done substantial amounts of PL/SQL.  I spent about 5 years as a PL/SQL developer and I'm still not sure whether or not I like the language.  :)

Although, PL/SQL did seem to be a dream like language after writing step triggers for Oracle Forms 2.3.  Now THAT is a WTF.

One of my proudest accomplishments was porting an encryption routine from C to PL/SQL.  Encryption is extra-fun when you don't have bit manipulators.  I was prepped for that one a bit by first porting the same routine into PowerBuilder in a prior project.

Re: All Talk and No Code

2005-12-07 15:52 • by WWWWolf
GaidenCommander? Um, did they also have a class BattlecruiserStrikeDecimatorPlus or something? Did the naming conventions include "All class names must sound like attacks performed by anime characters"?

Comments in non-native language are fun. In a project I worked on, a fellow programmer added (in Finnish) a helpful comment next to a hideous temporary hack: "the implementors of this function are highly skilled professionals of the field, and complete idiots. Dear kids, please don't try this at home." The manager did understand the humor, but the first comment from them was that the comments were supposed to be in English...

Re: All Talk and No Code

2005-12-07 16:24 • by Gene Wirchenko
52835 in reply to 52832
WWWWolf:
GaidenCommander? Um, did they also have a class BattlecruiserStrikeDecimatorPlus or something? Did the naming conventions include "All class names must sound like attacks performed by anime characters"?


For another take on this:
http://sluggy.com/daily.php?date=051126

Comments in non-native language are fun. In a project I worked on, a fellow programmer added (in Finnish) a helpful comment next to a hideous temporary hack: "the implementors of this function are highly skilled professionals of the field, and complete idiots. Dear kids, please don't try this at home." The manager did understand the humor, but the first comment from them was that the comments were supposed to be in English...


Snigger!

Sincerely,

Gene Wirchenko

Re: All Talk and No Code

2005-12-07 16:52 • by ammoQ
52837 in reply to 52825
RevMike:

I've actually done substantial amounts of
PL/SQL.  I spent about 5 years as a PL/SQL developer and I'm still
not sure whether or not I like the language.  :)

Although, PL/SQL did seem to be a dream like language after writing step triggers for Oracle Forms 2.3.  Now THAT is a WTF.





You were actually exposed to the idocy of trigger steps? I feel sorry for you... I was more lucky,

three times I managed to escape from Forms 2 and my first SQL*Forms
project was already with version 3 and PL/SQL. The biggest WTF in
Oracle Forms was about COMMIT; too bad I don't have the code of that
old Forms3 project, where almost every form had a block referencing the
DUMMY table, so a commit could be performed; it would be a nice WTF for
this site.

(For you non-Oracle-aggrieved guys: in Forms, fields are organised in blocks; every block can be bound to a database table, so that changes in the fields
(by the user or programmatically)  automatically cause
corresponding update/insert/delete statements on the table. Forms does
(in all versions I know) not perform a commit unless at least one
insert/update/delete is performed that way. Too bad if you want to
encapsulate all update statements in PL/SQL blocks...)




One of my proudest accomplishments was porting an
encryption routine from C to PL/SQL.  Encryption is extra-fun when
you don't have bit manipulators.  I was prepped for that one a bit
by first porting the same routine into PowerBuilder in a prior project.




That's what they told us about the Turing machine; if it can be
programmed at all, it can be programmed in any turing-complete language.

Re: All Talk and No Code

2005-12-07 17:28 • by RevMike
52838 in reply to 52837
ammoQ:
RevMike:

I've actually done substantial amounts of
PL/SQL.  I spent about 5 years as a PL/SQL developer and I'm still
not sure whether or not I like the language.  :)

Although, PL/SQL did seem to be a dream like language after writing step triggers for Oracle Forms 2.3.  Now THAT is a WTF.





You were actually exposed to the idocy of trigger steps? I feel sorry for you... I was more lucky,

three times I managed to escape from Forms 2 and my first SQL*Forms
project was already with version 3 and PL/SQL. The biggest WTF in
Oracle Forms was about COMMIT; too bad I don't have the code of that
old Forms3 project, where almost every form had a block referencing the
DUMMY table, so a commit could be performed; it would be a nice WTF for
this site.

(For you non-Oracle-aggrieved guys: in Forms, fields are organised in blocks; every block can be bound to a database table, so that changes in the fields
(by the user or programmatically)  automatically cause
corresponding update/insert/delete statements on the table. Forms does
(in all versions I know) not perform a commit unless at least one
insert/update/delete is performed that way. Too bad if you want to
encapsulate all update statements in PL/SQL blocks...)





I was the technical lead on a project taking an
internally developed financial system from DOS-Forms 2.3-SQLNET
1-DECNET to Win95-Forms 4.5-SQLNET 2-TCP/IP.  We off-shored the
conversion of the forms to a company that promised they could do an
automatic conversion.  Apparently they had a tool to do conversion to
Forms 3.0, then another tool that would convert to Forms 4.5.  By the
time it was done, the code was a mess of 'goto's, but we got it working
in time for Y2K.

DECNET had a nice utility that allowed you to
execute a command on another server, connecting the standard in/out/err
streams to the local process across the network.  I don't remember the
details, but nothing we found in the standard TCP/IP based stack worked
quite the same way.  I wound up writing a utility that would create a
DCL (VMS shell language) script, ftp it to the host, rexec it, and ftp
the result back to the client.  It was a big WTF, but I was able to
isolate it into a library so noone else needed to see it.

Re: All Talk and No Code

2005-12-07 17:49 • by brazzy
52839 in reply to 52832
WWWWolf:
Comments in non-native language are fun.




I once knew a guy who had actually worked on translating Japanese
console games for the US market. The text he had to translate did NOT
come in nice, separate resource files, it was embedded in the code. And
he was also supposed to translate the comments in the code (which were
all Japanese) so that the coders of the US licensee would have an
easier time of making modifications.



In one game, he found a comment at the top of a file that said "Hi, I'm
$NAME, I'm a programmer here, and I'll write my comments in Kansai
dialect" - of course in strongly Kansai-accented Japanese.



It had me in stitches, though I guess it's not half as funny if you don't understand Japanese and can recognize the dialect.

Re: All Talk and No Code

2005-12-07 21:18 • by Anonymous Chicken

Please inform him that Aleph is NOT a silent letter, unless I have been misspelling my first  name for the past 30 years.
Why do I feel he will still argue ?

Re: All Talk and No Code

2005-12-08 04:23 • by DaveW
52854 in reply to 52779
Jens:


At my current place of employment we are discuraged from putting
comments in our code in general. The two exceptions to this exist rule,
is API programming and code which cannot be made self-explanatory and
therefore deserved commenting. The reason for this being that comment
are often not updated as the code evolves, thus ending up being
misleading to the maintenance programming in the end. Obviously this
approach this approach assumes that an effort is being made to keep the
implementation as clean. What are our thought on this approach to
commenting?






If the comments are not updated as the code evolves, are the
"self-documenting" function and variable names going to be updated any
more often?  I've seen plenty of examples where the latter reflect
the original, rather than the current meaning.  At least comments
are easier to change - you only need to change them locally, not
everywhere the identifier is referenced.

Re: All Talk and No Code

2005-12-08 13:35 • by Zlodo
52882 in reply to 52769
AlfAlf:

Well, it may come as a surprise to you that not all french canadians
are able to write properly sentenced comments in english. Where i work,
comments used to be made in english (as is everything in the code) but
after having comments that we're so badly written that they were more
confusing than anything else, we opted to have all comments written in
french.
I agree that in a perfect world, i should be all written in the same
language, but in the real world, that is not always possible.
I see no WTF in this, i live it everyday. Sadly, i live in the real
world.






As the submitter of the second comment (which comes from some code in
my previous company that actually originated from another company), I
would like to mention that there weren't much in the way of comments in
the code anyway, and that they were badly spelled, had bad grammar, and
sometimes barely made any sense at all.





By the way, I'm french and even when I was working for french
companies, I was always writing my comments in english. One french
company I worked for actually demanded that, just in case they would
need to get foreign subcontractors to work on the code at a later
point, which IMO is a sound decision.





By contrast, the company from which the second comment originates is a
france-based international company, with development going on in
several places in the world, so writing french comments was really
stupid :)





Anyway, most of the programming material you find on the net is in
english, so any programmer who can't be bothered with english is a
crippled one imo.

Re: All Talk and No Code

2005-12-08 15:30 • by MikeB
52903 in reply to 52731
DisturbedSaint:
MikeB:
///  The Nessie Variable is the ultimate storage container

/// for truth....

/// Last week Japanese scientists ex-placed...
/// placed explosive detonators at the bottom of Lake Lochness
/// to blow Nessie out of the water. Sir Cord Godfried of the
/// Nessie Alliance summoned the help of Scotland's local wizards
/// to cast a protective spell over the lake and its local residents.
/// And all those who seek for the peaceful existence of our underwater ally.

If Nessie IsTrue() Then..... [<:o)]



dude, you like that movie *way* too much...

-ds


IsTrue


[pi]

Re: All Talk and No Code

2005-12-09 04:46 • by ammoQ
52967 in reply to 52882
Zlodo:



Anyway, most of the programming material you find on the net is in
english, so any programmer who can't be bothered with english is a
crippled one imo.


This is only partially true; because although every programmer must understand English words like "class", "loop" or "statement", there may be many domain-specific words which are not readily understood in English, only in the native language.

Re: All Talk and No Code

2005-12-09 18:01 • by Arjan
53031 in reply to 52750
Paul Abraham:
I always feel sorry for non-English speakers who are forced to program in English.

Well, not being English, I could feel sorry for the native English speakers having to deal with all those English computer words that actually have a meaning in non-computer life as well! Isn't it quite odd to use the name "Windows" while using the very same word for, errrr, windows? Browser? The home and escape key? Directory? A set-top box? Oracle? Doesn't the missing R in RFC 1945's Referer bother you?


And above all:


Hello World? ;-)

Re: All Talk and No Code

2005-12-10 18:10 • by styx
53049 in reply to 52750

Paul Abraham:
As a native English speaker myself (from the place that has given its name to the language, no less), I always feel sorry for non-English speakers who are forced to program in English.  Perhaps it's time to redress the balance.

French example:

si(condition)
    // quelquechose
ousi(condition2)
    // encore quelquechose
fin

German example:

wenn(condition)
    // etwas
oderwenn(condition2)
    // noch etwas
Ende

I'm sure our French and German friends could do better.


*shudder* sounds like excel.


never got the hang on iif,though..

Re: All Talk and No Code

2005-12-12 15:13 • by ARKBAN
I'm the author of the first comment, the GaidenCommand one. Just a minor few points:
- The GaidenCommand is a private, implementation dependent, inner class for a more reasonably named class called the "CommandManager."
- The poster also conviently deleted the comments explaining what the class does. Makes for a better WTF : ) I'l repost the entire comment here:

        ///
        /// The GaidenCommand is a specialized Command for use by the
        /// CommandManager. The GaidenCommand is directly hooked up to some UI
        /// object, and when that UI object is triggered, it triggers the
        /// GaidenCommand.
        ///
        /// The GaidenCommand contains a regular, user-supplied Command. As
        /// described above, when the GaidenCommand is triggered, it will
        /// execute the user-supplied Command (if it has one).
        ///
        /// Note, the word "gaiden" is Japanese and means "side story",
        /// see "http://en.wikipedia.org/wiki/Gaiden".
        /// Why did I call this "GaidenCommand"? Because it's very similar to
        /// a regular Command, but it serves the CommandManager in a different
        /// way, and it is not the same as a regular "Command". Also
        /// "CommandManagerCommand" is far too long to write. I also toyed with
        /// calling this the "AlephCommand", Aleph being a silent Hebrew
        /// letter, but Gaiden sounded better.
        ///

        private sealed class GaidenCommand : ICommand { ... }

Why did I name it Gaiden? Because I was hard pressed to think of something more appropriate.

I thank the poster for not coming by and suggesting a better name, and trying to nail me on a naming issue versus the quality of the design behind it.

ARKBAN


Re: All Talk and No Code

2005-12-12 15:15 • by ARKBAN
53122 in reply to 52847
I'm newly learning Hebrew, and in Hebrew the aleph is a silent letter. If it has a vowel it has a sound, but by itself it has a sound. Please correct my if I'm wrong, as I said I'm new to Hebrew.

Re: All Talk and No Code

2005-12-12 15:49 • by Joost_
53133 in reply to 53122
How about IndirectCommand. Or MetaCommand. Or CommandCommand (yes
that's weird). I don't now the difference in functionality between a
GaidenCommand and a Command, but I sure as hell bet that the difference
between the functionalities of a GaidenCommand and a Command isn't a
'Side story'.

Re: All Talk and No Code

2005-12-12 17:23 • by ARKBAN
53152 in reply to 53133
I decided the best approach was to throw the meaning as
far from away as possible rather than create a lot of difficulty
relearning or alterning an existing concept. (In truth I renamed the class at least 3 times with a thesaurus in hand trying to thing of something better).  Trying to make one learn a
subtly different definition of a word is much harder than learning a totally
new word. The former you must unlearn what you learned, or at worst try
to mentally keep track of two different concepts and figure out which
applies and what are the subtle differences. It unfortunately goes against what a human brain is good at.



So rather than the reader going "Wait, I know what XXX means, but is
this isn't XXX at all, where are the differences and commonalities" I took the approach of forcing the reader to
say "WTF is this? I better read this over carefully (or go ask the guy
who built it)." I guess you could argue it's an intentional WTF, to try
and prevent the reader from improperly applying any (possibly invalid)
assumptions (a mistake I've seen happen far too often).

I've yet to see a good solution for this sort of naming issue, and I include mine in that pile of bad solutions.


Also I want to mention that I always follow this sort of statement "I have commented just about everything; you should be able to figure it out without a problem." with "but come ask me any questions" and "if you see away to improve the comments and/or code, let me know how". The amount of out-of-context the submitter used is priceless.

I'm disappointed that it's not as difficult as I thought to trick the
Daily WTF. But I guess that's my issue, I was gullible and believed
that one would not intentionally manipulate code to make it worse than
it was, or post it to Daily WTF without ever mention the issue or offering a better solution
to the author.

ARKBAN



Re: All Talk and No Code

2005-12-13 18:14 • by Arjan
53282 in reply to 53152

Anonymous:
I'm disappointed that it's not as difficult as I thought to trick the Daily WTF. But I guess that's my issue, I was gullible and believed that one would not intentionally manipulate code to make it worse than it was, or post it to Daily WTF without ever mention the issue or offering a better solution to the author.

ARKBAN


Come on, smile, learn from the comments people have posted and don't try to talk your way out of it by blaming this wonderful web site. This site is not about nailing people.


I really think that the full documentation you posted, in which you're repeating yourself but in my opinion really are not clarifying anything at all, only makes the WTF worse. And you even claim you've renamed the class at least three times -- then how much time did you spent on writing that comment and how much money did you make for that?


Anonymous:
Also I want to mention that I always follow this sort of statement "I have commented just about everything; you should be able to figure it out without a problem." with "but come ask me any questions" and "if you see away to improve the comments and/or code, let me know how".


Agreed, it would have been nice if you would have received feedback. But the WTF is not about whether or not you're willing to spend even more time on the documentation. It is about the documentation you released, and which appearently you still think is well written. I agree with the one who submitted it as a WTF: I think it is useless, and a waste of time both for yourself and the one who's to maintain the code.


By the way: how could a "private, implementation dependent, inner class" be "directly hooked up to some UI object"? Truth or dare: please post the code that was following the submitted comment?


Arjan.

Re: All Talk and No Code

2005-12-14 10:08 • by anon
53337 in reply to 52743
According to Terry Pratchett, it would have to be one of those million to
one chances: bound to happen, but only if the odds are EXACTLY a milion
to one!

Re: All Talk and No Code

2005-12-15 04:40 • by random garbage
53461 in reply to 53049

styx:



*shudder* sounds like excel.



never got the hang on iif,though..




Really? I always thought IIf was relatively simple, rather like the
ternary ?: operator in C-ish languages... It helps that I read
somewhere that IIf stood for (or could be interpreted as) "Immediate
If", which is effectively what the ternary operator is...


IIf (a , b, c)

and

a ? b : c ;


are both compact representations of


 if (a) then b else c 


which can be evaluated as an expression, and thusly used on the right hand side of an expression...


Re: All Talk and No Code

2005-12-15 12:55 • by Zlodo
53491 in reply to 52967
ammoQ:

This is only partially true; because although
every programmer must understand English words like "class", "loop" or
"statement", there may be many domain-specific words which are not
readily understood in English, only in the native language.




Well, it depends on which domain. Take computer science, for instance:
most of the theory and stuff behind it originated from english-speaking
countries, so most of the domain-specific terms are actually english,
and most of them don't have any useful translations - at least in
french (I don't know how it goes for other languages).

Of course, some books try to litteraly translate them, which makes for
ridiculous and annoying results. The concept of template in C++, for
instance, is known as template, even among french programmers.

In the french edition of stroustrup's book, they translated it into
"modèle". So you then have to perform the mental gymnastic of
translating it back to template.



Anyway, my point wasn't about the keywords used in the language, but
rather about the availability of knowledge, articles, litterature,
forums and so on in english compared to french.

Google may be the best programming tool around, if you can read and
write english. It's not such a good tool if you can only search for
information in, for instance, french.

Re: All Talk and No Code

2005-12-17 14:54 • by kengaroo
53736 in reply to 52731

stupid ass[:@]


lol


looser


loose


looooooooooooooooooooooooooooser


looooooooooooooooooooooooooooooooooser


looooooooooooooooooooooooooooooooooooooseer


loooooooooooooooooooooooooooooooooooooooooser

Re: All Talk and No Code

2005-12-18 11:31 • by Zorro
53762 in reply to 53120
ARKBAN, you want feedback, here's mine:

1. you could have done withoug this.

        /// Why did I call this "GaidenCommand"? Because it's very similar to
        /// a regular Command, but it serves the CommandManager in a different
        /// way, and it is not the same as a regular "Command". Also
        /// "CommandManagerCommand" is far too long to write. I also toyed with
        /// calling this the "AlephCommand", Aleph being a silent Hebrew
        /// letter, but Gaiden sounded better.

I think this is the most 'wtf' part of the comment. Putting a "I" in
there and spending 6 lines telling your story on why you choose the name
... I understand you spend time thinking about a name, but I don't really need to know what.

2. you could probably have done without this one too:

        /// Note, the word "gaiden" is Japanese and means "side story",
        /// see "http://en.wikipedia.org/wiki/Gaiden".

If you need to spend a large amount of time explaning a name (or a link to wikipedia), maybe it's not the best name possible. Frankly, I think something like CommandManagerCommand (or CMCmd) even if less aesteticly pleasing does the job done just fine.

my $.02. Peace.

Zorro.



Re: All Talk and No Code

2005-12-18 13:18 • by Zorro
53763 in reply to 53762
Also,

    /// "CommandManagerCommand" is far too long to write.

too long to write? Any modern code editor (windows IDE or unix vim/emacs) has name auto-completion. I'd trade a
'what does that mean' to a 'long to write'/'hit-autocompletion-key' name any day of the week.


Re: All Talk and No Code

2006-01-16 04:13 • by Anonymous
I have to defend ARKBAN here. Obviously if he puts this much thought into choosing all of his identifiers, he's going to end up in the loony bin, but I'm assuming he doesn't. It sounds to me like he simply encountered an awkward naming problem that stumped him. Sure, his solution was in the end worse than the disease, but all of his extra commenting indicate to me he had sense to draw attention to the problem. A funny name with a comment could be very helpful to a reader as a marker of an unusal or novel pattern. 'CommandManagerCommand' is not really acceptable either. Again, I'm sure there are dozens of better solutions to this naming problem, but at least he was conscientious about it.



BTW, how the crap am I supposed to just add a new post to the thread? Why am I made to reply to an individual post?

Re: All Talk and No Code

2006-01-16 07:20 • by masklinn
56792 in reply to 53461
Anonymous:

styx:



*shudder* sounds like excel.



never got the hang on iif,though..




Really? I always thought IIf was relatively simple, rather like the
ternary ?: operator in C-ish languages... It helps that I read
somewhere that IIf stood for (or could be interpreted as) "Immediate
If", which is effectively what the ternary operator is...


IIf (a , b, c)

and

a ? b : c ;


are both compact representations of


 if (a) then b else c 


which can be evaluated as an expression, and thusly used on the right hand side of an expression...



Except that IIf(f(a), g(b), h(c)) evaluates f(a), g(b) and h(c) while f(a)?g(b):h(c) evaluates either f(a) and g(b) or f(a) and h(c) (same thing for the if/then/else construct)

« PrevPage 1 | Page 2Next »

Add Comment