Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

CodeThatDocumentsItselfSoWellItDoesNotNeedComments

thedailywtf.com

Post reply on HN
Print view View original

31–40 of 40 posts

Re: CodeThatDocumentsItselfSoWellItDoesNotNeedComments

#31

Post by joe_the_user »

mkyc wrote: post #29
edw519 wrote: post #28

Earlier quoted context omitted.

The moral of the story is not to use shorter names, but to write better code. The scope of the post was variable naming. I used dates and "The Three Bears" for a light example of variable naming that almost anyone could understand. I did not even begin to address "better code". I'll save that for another (or hundreds of other) posts. Your Mama Bear example is some seriously broken date iteration code (so you change l…

My point is that naming verbosity depends on the code. This is vague but better than saying "cf. Goldilocks" ("choose anything between two crazy extremes"). My other point is that everyday use of names should be a guide for naming in code. The reason Mama Bear is wrong is that she's too formal. She gives a full explanation of the variable each time, but the 'full explanation' is the responsibility of the var setters,…

I'm shocked the above viewpoint has not gotten the majority of votes, it should.

Re: CodeThatDocumentsItselfSoWellItDoesNotNeedComments

#32

Post by redcap »

DannoHung wrote: post #24
DannoHung wrote: post #20

Well, you can tell the developer of that was Indian.

I actually wasn't trying to be derogatory. "Do the Same" is a pretty common Indian English phrase. Just like "Do the Needful".

And if you squint just a little bit you can understand what they're trying to say instead of getting on a rant horse about proper English grammar.

Re: CodeThatDocumentsItselfSoWellItDoesNotNeedComments

#33

Post by joe_the_user »

pmichaud wrote: post #3

I would rather support that, than most of the code I've actually been asked to support.

I bet the real code had all the other problems of real code PLUS the absurdly long names.... At that rate, I'd worry about carpal tunnel syndrome.

Re: CodeThatDocumentsItselfSoWellItDoesNotNeedComments

#35

Post by grandpa »

IsaacSchlueter wrote: post #25

There's a lot of "short vs long" going on in the comments here. That seems silly to me. Code should be written so as to completely describe the program's functionality to human readers, and only incidentally to be interpreted by computers. We have a hard time remembering short names for a long time, and we have a hard time looking at long names over and over again in a row. Additionally, short names carry a higher li…

> Another way to look at this: The first time you meet > someone, you learn their full name. When discussing them > with someone else who knows them, you use just a single > name. If they're standing right there, you don't bother > using their name, but just make eye contact, and maybe a > "Hey". Should be the same way with variables.

What an awesome way to think about this. Thank you.

Re: CodeThatDocumentsItselfSoWellItDoesNotNeedComments

#36

Post by tetha »

joe_the_user wrote: post #33
pmichaud wrote: post #3

I would rather support that, than most of the code I've actually been asked to support.

I bet the real code had all the other problems of real code PLUS the absurdly long names.... At that rate, I'd worry about carpal tunnel syndrome.

some letters + (In eclipse) Ctrl+Space, (in Vim) or in insert mode beat CTS with long names.

Re: CodeThatDocumentsItselfSoWellItDoesNotNeedComments

#37

Post by tetha »

rapind wrote: post #7
pmichaud wrote: post #3

I would rather support that, than most of the code I've actually been asked to support.

Is it really all that difficult to throw in a comment explaining what it is you're trying to do when it's not obvious to someone other than yourself?

This is however a major problem I have with comments: If it is obvious to me, my mind never ever spends a conscious second thinking about this. For me, the problem does not exist at all. So, tell me, how am I supposed to comment something which might be not obvious to someone else if I don't know it is there?

Re: CodeThatDocumentsItselfSoWellItDoesNotNeedComments

#38

Post by dratman »

IsaacSchlueter wrote: post #25

There's a lot of "short vs long" going on in the comments here. That seems silly to me. Code should be written so as to completely describe the program's functionality to human readers, and only incidentally to be interpreted by computers. We have a hard time remembering short names for a long time, and we have a hard time looking at long names over and over again in a row. Additionally, short names carry a higher li…

So obviously variables should be able to have more than one name: a long one and a short one. SQL offers the ability to define an alias name.

Unfortunately that would be a kind of kitchen sink feature that no standards committee is likely to accept. As a substitute, one could create a variable with a long name, then put the value into another variable with a short name, but that could be confusing unless very clearly noted in a comment.

Re: CodeThatDocumentsItselfSoWellItDoesNotNeedComments

#39

Post by plaes »

IsaacSchlueter wrote: post #25

There's a lot of "short vs long" going on in the comments here. That seems silly to me. Code should be written so as to completely describe the program's functionality to human readers, and only incidentally to be interpreted by computers. We have a hard time remembering short names for a long time, and we have a hard time looking at long names over and over again in a row. Additionally, short names carry a higher li…

My approach is basically the same:

Long-uppercased names for anything global, settings or security-related (ie COOKIE_NAME, SECRET_HASH)

For dummy loop variables: i, j, k

For everything else I use common sense.

Re: CodeThatDocumentsItselfSoWellItDoesNotNeedComments

#40

Post by philluminati »

IsaacSchlueter wrote: post #25

There's a lot of "short vs long" going on in the comments here. That seems silly to me. Code should be written so as to completely describe the program's functionality to human readers, and only incidentally to be interpreted by computers. We have a hard time remembering short names for a long time, and we have a hard time looking at long names over and over again in a row. Additionally, short names carry a higher li…

The same point was made in the book "Clean Code"
Post reply on HN