Win a copy of Learning Regular Expressions this week in the General Computing forum!
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Liutauras Vilda
  • Campbell Ritchie
  • Tim Cooke
  • Bear Bibeault
  • Devaka Cooray
Sheriffs:
  • Jeanne Boyarsky
  • Knute Snortum
  • Junilu Lacar
Saloon Keepers:
  • Tim Moores
  • Ganesh Patekar
  • Stephan van Hulst
  • Pete Letkeman
  • Carey Brown
Bartenders:
  • Tim Holloway
  • Ron McLeod
  • Vijitha Kumara

Naming code entities is not a matter of taste  RSS feed

 
Ranch Foreman
Posts: 142
5
BSD Debian Open BSD
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
In coding, we choose names for variables, fields, methods, classes, packages etc. Names are meaningful in the human domain in machine domain doesn't matter,
meaningful naming help us, our colleagues,  maintenance developers to not confuse ourselfs and others and spend more time trying to decipher the code than necessary.
Names are underestimated but play a crucial role

1. Thing names as an auto-documentig mean
Most people hate writing documentation, because

a. it takes away time from coding
b. gets outdated quickly
c. and probably is not read anyway

On the other hand Not writing documentation means, however, that others will have to understand the code. Luckily, there is a simple way out:
All language elements, from classes to local variables, have names that you can use to express your intention in writing the code. Knowing your intention will help future
readers to grasp the working of the code


2. Take your time in finding the most appropriate names
Describe your entities as precisely as possible(avoid general names If a concept is very general, you should qualify it further through composite names e.g. IdentityHashMap
), if your vocabulary is poor use a dictionary for inspiration about closely related words.
Fortunately nowadays IDE's  provide refactoring support to emphasize that renaming is a proper structural code modification that does not alter the meaning
of the code.

With all that tools in place here's no excuse for keeping bad names. On the other hand one thing to consider carefully is the naming in the public interface of our software,
If our software offer functionality/services  to others, and we change naming our clients’ code will be broken.

3. Use similar names for similar things, and different names for different things
This helps avoid confusion e.g.If you  see a ScreenManager and a Display name in the system, you will assume that the former actually manages the latter. If this is the
case, rename ScreenManager to DisplayManager; otherwise, choose a completely different name, such as WindowLayoutManager (if that is its task)

4. Don't use abbreviations instead make names pronounceable
Auto-completion tools invalidates the excuse that abbreviations reduce the typing effort.

5. Choose names such that the source code is easily understandable
Make it a habit to look through code that you have just finished and to rearrange and rename until you are satisfied with the story the code tells.

 
Marshal
Posts: 60199
188
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Harry Kar wrote:In coding, we choose names for variables, fields, methods, classes, packages etc. . . .

Is that quoted from anywhere? If so, please always tell us where.

. . . On the other hand Not writing documentation means, however, that others will have to understand the code.

Documentation is essential, because you want to be able to distribute compiled code in a .jar and have people understand how to use it. That means you can restrict access to the code to people who maintain or enhance the code. There is a difference between understanding the code and understanding how to use it. Also have a look at Joshua Bloh's Effective Java, particularly the part about “Design and document for inheritance or else prohibit it” (in 3rd edition page 93).

2. Take your time in finding the most appropriate names. . .

That is all good stuff
Good naming doesn't mean you don't need documentation; you need both.
 
Harry Kar
Ranch Foreman
Posts: 142
5
BSD Debian Open BSD
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Campbell Ritchie wrote:

Harry Kar wrote:In coding, we choose names for variables, fields, methods, classes, packages etc. . . .

Is that quoted from anywhere? If so, please always tell us where.


For almost every read i had from magazines  books or net i take some hand on notes but frankly i don't remember from where i took that notes (my notes last some years) 


Campbell Ritchie wrote:

Harry Kar wrote:On the other hand Not writing documentation means, however, that others will have to understand the code.

Documentation is essential, because you want to be able to distribute compiled code in a .jar and have people understand how to use it. That means you can restrict access to the code to people who maintain or enhance the code. There is a difference between understanding the code and understanding how to use it. .



Right  one of the strong points of OO is the use of the client server model mean the client of your code have to know only the specifics and nothing more (implementation details) and the specifics is documentation that you have to provide with your code in order to be usable without headaches from the client developer

Campbell Ritchie wrote:Also have a look at Joshua Bloh's Effective Java, particularly the part about “Design and document for inheritance or else prohibit it” (in 3rd edition page 93).



When available in biblio surely i lend it i have heard good words about that text


Campbell Ritchie wrote:

Harry Kar wrote:2. Take your time in finding the most appropriate names. . .

That is all good stuff .



Agree i put it here mainly for who comes from the C like world and for novices too

Campbell Ritchie wrote:Good naming doesn't mean you don't need documentation; you need both.


You know  who comes from an non OO environment is not accustomed (too much)  with documentation and other Software Engineering stuff almost obey at the list minimum(but also important in his own) i.e. naming diligently  is a great leap in my humble opinion
 
Harry Kar
Ranch Foreman
Posts: 142
5
BSD Debian Open BSD
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Campbell Ritchie wrote:That means you can restrict access to the code to people who maintain or enhance the code.



By the way the naming advises are referred to that people(who have source code access)
 
Harry Kar
Ranch Foreman
Posts: 142
5
BSD Debian Open BSD
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
A nice page about bad naming
 
Campbell Ritchie
Marshal
Posts: 60199
188
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Harry Kar wrote:. . . For almost every read i had from magazines  books or net i take some hand on notes . . .

Thank you.

. . . client server model mean the client of your code have to know only the specifics . . . 

I meant client code as code which uses another class (the supplier); the using class has to know how the interface of the used class works, not its implementation details. But that does entail documentation.
I take your point that lots of people don't document their code early enough; that is not at all good practice.
 
Harry Kar
Ranch Foreman
Posts: 142
5
BSD Debian Open BSD
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Campbell Ritchie wrote: ...I take your point that lots of people don't document their code early enough; that is not at all good practice.



That's why we strive to make/have a better world ;)
 
Ranch Hand
Posts: 150
3
C++ Eclipse IDE Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
today everyone says it's bad to put the type into the variable name, such as done with hungarian notation, why is it bad? to me this would be more understandable and self-documenting since you don't have to go hunt for where it's declared.
helps to prevent using it wrong such as in C for type safety.

for my own programs i can remember what everything is, but in someone elses code i would prefer to know at a glance what a certain var is. so why is it bad, convince me!
 
Sheriff
Posts: 12357
201
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

S Fox wrote:for my own programs i can remember what everything is, but in someone elses code i would prefer to know at a glance what a certain var is. so why is it bad, convince me!


Nobody needs to convince you of anything; do what you think is best. That said, the man for whom this notation was named--Charles Simonyi is Hungarian--even wrote an article regretting ever introducing the notation because of how many more people misunderstand and abuse its use rather than use it as he had intended. Basically, he wanted to express intent with it, not implementation. Abusers, as they are wont to do, screw it up for the rest of us.
 
Harry Kar
Ranch Foreman
Posts: 142
5
BSD Debian Open BSD
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
take a look here and here
 
S Fox
Ranch Hand
Posts: 150
3
C++ Eclipse IDE Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
i know you do code review professionally Junilu, so you will know better than anyone about all this, but here is how i think of it.

the argument against seems to always be, if the implementation changes then the type would be wrong. isn't that a good thing? now you know by looking at that code something could be amiss. obviously if you change the implementation you should of changed it everywhere, as well as the var name itself.

also i see they are saying the modern day ide can display the type so we don't need this naming convention anymore. true, but i learned to code in a simple text editor, not an ide, maybe some people still do that. and what if you are looking at a paper printout of the source?

in the classroom teachers are using strFileName, ptrFileA, ptrFileB, that's how they always did it in my classes. i don't do it in my own code because i know its not the modern accepted way. why are teachers doing this if they know its wrong?

you can see stroustrup saying he's not in favor of hungarian but likes it for untyped languages, but then he also says he likes variable_name instead of variableName, so he is not in favor of camelcase which is the most common convention today.
he also argues against long var names, but in java reallyReallyLongNamesLikeThis are the style here.

then there is the whole style debate about declaring pointers, is it int* p; or int *p;
i prefer the 2nd way since when declaring more on one line it looks like int *p, *p1; so it's more correct to me, of course stroustrup disagrees, says just don't put more onto one line so he can pretend int* is it's own special type.
wouldn't it be better to just check with k&r to see how they did it? they wrote the book on C, and all these other languages are variants of it. i am guessing they used *p but i didn't look it up to be sure.

we could then go into the curly brace style and comments styles too, many variations on that. i'm not sure what the most accepted block comment style is today and i wonder about that a lot.

stroustrup says:

Whenever something can be done in two ways, someone will be confused. Whenever something is a matter of taste, discussions can drag on forever.


yep!

so i think it really is a matter of taste, because compilers don't care about whitespace and formatting. none of this really matters to the compiler, it's all just a formatting style that we humans are trying to follow. each group of people seems to have their own way, even java ranch has a style guide page.
 
Junilu Lacar
Sheriff
Posts: 12357
201
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

S Fox wrote:in the classroom teachers are using strFileName, ptrFileA, ptrFileB, that's how they always did it in my classes. i don't do it in my own code because i know its not the modern accepted way. why are teachers doing this if they know its wrong?


To be fair, not all teachers do that but those who do are painfully out of touch with current norms and practices. This is not uncommon either. Some teachers don't even know that TDD is a thing and it has been around for quite some time now.

I follow Kent Beck's Four Rules of Simple Design, the second of which is that the code must be expressive, the third being that there is no duplication.  The misunderstanding and misuse/abuse of Hungarian notation leads to code that violates both these rules. Expressiveness is diminished by the unpronounceable wart you put in front of the name. Duplication is there because in typed languages like C/C++ and Java, the type is part of the declaration. Wherever you use the name with the little Hungarian type wart, you're duplicating knowledge in your code. Sure, IDEs can quickly refactor everything if the type changes and you need to change the Hungarian type wart but that doesn't eliminate the duplication. It's still there. Only by eliminating the Hungarian type wart in the name can you leave the single place where the type is found, in the declaration.

If you limit scope judiciously and follow the fourth rule to keep things small, then you never have to move your eyes very far from where you see the name to be able to see its type declaration. At worst, you'd have to look back at the top of the class. But if you follow rule #2 to make names expressive, the name you choose should also make the type kind of obvious. Otherwise, you'd be violating another principle: The Principle of Least Astonishment (POLA).
 
S Fox
Ranch Hand
Posts: 150
3
C++ Eclipse IDE Java
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
is it bad to use a variable in another namespace? that would allow using it really far away from where it was defined, in a whole other class file.
 
Junilu Lacar
Sheriff
Posts: 12357
201
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

S Fox wrote:but in java reallyReallyLongNamesLikeThis are the style here.


I don't necessarily agree with that. I would paraphrase Einstein and say that names should be as long as they need to be expressive, but no longer.

Additionally, excessively long names can also hint at code smells like when you have a method that really should be broken out into two or more different methods or could be refactored to a composed method.

One specific smell that you can commonly find in long names is when it contains a conjunction like promptUserAndPrintResult(). This should probably be broken up into two methods: promptUser() and printResult().
 
Junilu Lacar
Sheriff
Posts: 12357
201
Android Debian Eclipse IDE IntelliJ IDE Java Linux Mac Spring Ubuntu
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

S Fox wrote:is it bad to use a variable in another namespace? that would allow using it really far away from where it was defined, in a whole other class file.


Yes, that sounds pretty bad. It should at least be treated suspiciously and presumed guilty until proven otherwise. It is a violation of the 4th rule: Keep things small. In this case, the scope of the variable is not small. Why does the variable need to be accessible from outside the class? Would it make more sense to provide a getter? Even before considering a getter, would it be a smell of broken encapsulation? If so, then fix that first.
 
Greenhorn
Posts: 3
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks
 
Bartender
Posts: 1882
50
Eclipse IDE Google Web Toolkit Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I think that Naming code entities is actually a matter of taste.

We are humans after all, each person has a different perspective of looking at the world. Some of us are expressive in typing variables/class/methods/documentation. Some of us type the shortest word possible.
Many times, I resort to using acronyms such as : no, num, id, empId, etc... Typically, these are local variables and I have no issues reading them as number, employee id, etc.. But to a different person, they may not mean the same. I remember that I had to once modify a code that was written in German. All variables/methods/comments were completely foreign to me. This made me this re-think that my acronyms too might not make sense to someone from a different language background.  While we strive for a good naming convention, expecting everyone to follow the same format is simply not practical.

With regards to long naming conventions, here's an interesting quote from coding horror: (https://blog.codinghorror.com/new-programming-jargon/)

codinghorror wrote:Smurf Naming Convention
When almost every class has the same prefix. IE, when a user clicks on the button, a SmurfAccountView passes a SmurfAccountDTO to the SmurfAccountController. The SmurfID is used to fetch a SmurfOrderHistory which is passed to the SmurfHistoryMatch before forwarding to either SmurfHistoryReviewView or SmurfHistoryReportingView. If a SmurfErrorEvent occurs it is logged by SmurfErrorLogger to ${app}/smurf/log/smurf/smurflog.log


 
Marshal
Posts: 6015
415
BSD
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

salvin francis wrote:Many times, I resort to using acronyms such as : no, num, id, empId, etc... Typically, these are local variables and I have no issues reading them as number, employee id, etc..


From one side yes, you have no issues to decypher yourself and very likely other person wouldn't have problems either, BUT, imagine you have project of 1000 or more classes. Now you know you need to add something, fix something, remove something, here is where expressive, unambiguous and non-acronymed names help. You use IDE built in functionality or plugin to search for phrases across the project, and then you applause to somebody who spent slightly more time naming them in full and clearly, so you don't spend more than 1 minute to find exact place where you need to engage with. I even am for the Celsius over C and Fahrenheit over F, even though C and F meanings would be very clear in certain context.
 
salvin francis
Bartender
Posts: 1882
50
Eclipse IDE Google Web Toolkit Java
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I agree, they are not always good, hence I mentioned that :

salvin francis wrote:... But to a different person, they may not mean the same.


and

salvin francis wrote:This made me this re-think that my acronyms too might not make sense to someone from a different language background



 
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!