3

Could you give some good reasons for having the class name as part of the name of any variable? We use to have this policy, which I find quite useful. Some team member wants to revert the decision.

My arguments for the moment:

  • you can directly know what you're talking about:

    for (Student student: students) { ... }

is quite easy to understand (vs Student s or Student anyone)

  • it helps self-commenting the code
  • our ide provides direct support for that
  • you can directly see wheter you're using apples instead of pears (or bears ;-) )

Less confusion where subtle differences matter:

criteriaBuilder.equal(nameExpression, name);

The only argument I can see against this is that it makes the code longer (which I think isn't an issue with modern IDEs).

Is there public provisioning for such a recommendation? Anyone using the same rule? Any alternative?

Improve this question
26
  • 3
    You should name the variables so that it's clear what they contain/represent. The type is usually not important. Would you e.g. write String string = "Eric"? Commented Jun 20, 2011 at 13:33
  • Not quite sure what you are asking here: is it about writing "Student student" rather than "Student s" or "Student var"? Commented Jun 20, 2011 at 13:37
  • 1
    @DJClayworth,yes he is trying to say put the tpye in front of the varaible name ex: "Student studentJack = ...." Commented Jun 20, 2011 at 13:38
  • 1
    It seems fine to do something like Student studentJohn;. I agree that it makes it easier to differentiate variables later in the code. Commented Jun 20, 2011 at 13:38
  • 1
    @ymajoros - You're not going to find a proof that one method is better than the other. As with most style guidelines, you weigh both sides and make a choice as an organization. Hungarian Notation was more popular when IDEs were less powerful and before refactoring. I feel that it went by the wayside as the industry and tools matured. You'll still see it some places, but I've used it in only one of my projects since 1995, and that was because the existing codebase I extended used it. Commented Jun 21, 2011 at 7:41

4 Answers 4

Reset to default
7

That sounds like Hungarian Notation to me.

In principle it sounds like a good idea but I'm honestly not sure there are good reasons for it:

  • Self commenting / documenting code - this should be possible without putting types in the variable names;
  • An IDE should also provide support for seeing what type a variable is without putting it in the variable name (e.g. Eclipse can do this)
  • I don't know that this is really an advantage.

One problem with Hungarian Notation that you don't mention is that if you refactor code, you have to change all the variable names as well. There are plenty of examples on The Daily WTF where variables are named 'strSOMETHING' or 'intSOMETHING', even though the types are defined as something else.

In general, IMO the case for using Hungarian Notation is pretty flimsy and generally I wouldn't recommend making it a policy.

(If this isn't exactly what you are talking about, I apologise!)

Improve this answer
Sign up to request clarification or add additional context in comments.

10 Comments

That definitely does sound like Hungarian Notation. I can see the value in Hungarian Notation when using a loosely typed language like JavaScript but that can just lead to confusion when you expect an integer but receive an object, like the example you get.
I don't see where the example has an object when you expect an integer.
I even agree somewhat for some variables (counters). However, from my expericence, I think this should be a strict convention for objects. A "student" will probably stay as such.
BTW, most IDE can show the variable type, but this isn't obvious at first sight if you don't observe something like this.
A quite good blog article on what Hungarian notation was actually intended for: joelonsoftware.com/articles/Wrong.html
|
6

Your bible on this question is Steve McConnel's book, Code Complete, which is the most comprehensive book on software construction practice like this. He has a whole chapter on variable naming and why it is important.

The key is to make the name a full description of what the variable does, so that it is easy to understand for the person reading it. If it achieves that, then it's good practice.

Student student looks like a simple to understand policy, but it has an immediate disadvantage - it contains no extra information about the variable. You already know its a student. If you know anything else about the object then add it to the variable name - studentUnderReview, graduatingStudent etc. "student" should only be used if you know absolutely nothing else, such as the variable is used to iterate over all Students. Now in a long method it's useful to know the type by just looking at the name, but if the variable has short scope then it's marginal whether its useful or not. There are some studies (see McConnel) which indicate that for variables with very short scope, such as for loop indices, short names are better.

As soon as you have two variables, this system breaks down. If the default is to call one variable "student" then the temptation is to call two variables "student1" and "student2", which is bad practice indeed (see McConnel for details). You need to make names that describe the object - goodStudent and badStudent; studentBeingSaved and studentBeingRead.

Improve this answer

5 Comments

I'll definitively have a look on the book. If I have two Student variables, I usually name them in the style you suggest. My question was about a good reference on the subject, so your answer definitively is interesting.
One important topic that is only slightly touched in Code Complete is using units in the variable name. I consider putting the units in the variable a must, like timeoutMilliseconds instead of just timeout and putting the content type (that is not part of the variable type) as commentsHtml instead of just comments.
That's a good point, but if you are using a consistent set of units then it's unnecessary to put the units in the name. In the comments will suffice.
@DJClayworth The problem is that you may start with timeout being seconds and then you change it to milliseconds to have more resolution and it becomes a mess. If you rename the variable you make sure there are no references to the variable with the old units.
That's why I said "if you are using a consistent set of units". If you switch to not having a consistent set of units then yes, you may have to rename some variables.
2

The policy should be to use descriptive variable names. One-letter variable names are bad, but so are variable names based exclusively on class names. Your main argument is really for descriptive variable names.

As for the others:

  • it helps self-commenting the code - no, it duplicates information from the variable declaration
  • our ide provides direct support for that - that would only be an argument if the alternatives provide no benefits
  • you can directly see wheter you're using apples instead of pears (or bears ;-) ) - that's the job of the type system

Of course, if your class names are descriptive, then sometimes it will make sense to have variables with the same name - when the variable describes an instance of the class without any distinctive characteristics. As in your example:

for (Student student: students) { ... }

If you're looping over all students, this is fine. But if you have a non-generic instance of Student, the variable name should describe what particular role that student has in this part of the program (e.g. candidate or graduate).

Improve this answer

5 Comments

I agree for some parts, until the candidate/graduate examples. To me, candidateStudent is a more appropriate choice.
I'm with Michael on this. "Student candidateStudent" adds no information over "Student candidate".
@DJClayworth it does give visual type information that "candidate" doesn't give. In our big code repository, this is quite important. You can't always have to check the type.
@ymajoros: If variables are used far from where they're defined, you have a design problem, independant of code size, and type information is not the biggest part of that problem. Any Java IDE worth using will show you the type of a variable if you hover the cursor over it. There is a very broad consensus that "Visual type information" which duplicates the declared type is NOT a good thing (see the whole Hungarian notation debate).
it doesn't need to be used far from the definition to be difficult to read. In any non-trivial algorithm, naming a Student variable "graduate" gives the reader something to remember. In contrast, explicitly naming it "graduateStudent" makes everything clear.
1

Generally your variable names should help the developer see quickly what they actually represent. Student student would be ok if the relation that defines expresses a anything-to-student relation, like Student[] students (or better some collection of Student) would be ok for a class Professor or the like.

String string is generally a bad idea, since it doesn't say anything about the use of that variable. Better names would be String name, String description or similar. In some cases, where all that matters is that you're dealing with one string - like general string utilities - you might call the variable string but if you have two or more, you should use better names (e.g. source and target etc. depending on the class/method).

IMHO, adding prefixes/suffixes might be a good idea if they tell you something about the variable that its base name wouldn't, e.g. in a web environment you might deal with strings that are input by the user as well as escaped strings (e.g. to prevent code injection), so you might use a prefix/suffix to make a disctinction between the user input version and the escaped counterpart.

Improve this answer

3 Comments

I agree that String string isn't a good idea (in most cases; could be in a string utility method). But I always end my variable names with Str when they contain the string representation of something (which, in OOP, should be very different from the thing it represents).
@ymajoros you can do that if you have a string representation of something that isn't a string, but if you have a plain string object, you wouldn't call it nameStr for example, would you?
I wouldn't if it's obvious. I would if it needs to: String publicationDateStr (formatted date) vs Date publicationDate

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.