Use the plural for packages with homogeneous contents and the singular for packages with heterogeneous contents.
A class is similar to a database relation. A database relation should be named in the singular as its records are considered to be instances of the relation. The function of a relation is to compose a complex record from simple data.
A package, on the other hand, is not a data abstraction. It assists with organization of code and resolution of naming conflicts. If a package is named in the singular, it doesn't mean that each member of the package is an instance of the package; it contains related but heterogeneous concepts. If it is named in the plural (as they often are), I would expect that the package contains homogeneous concepts.
For example, a type should be named TaskCollection
instead of TasksCollection
, as it is a collection containing instances of a Task
. A package named com.myproject.task
does not mean that each contained class is an instance of a task. There might be a TaskHandler
, a TaskFactory
, etc. A package named com.myproject.tasks
, however, would contain different types that are all tasks: TakeOutGarbageTask
, DoTheDishesTask
, etc.
- Don't reuse same variable name in the same class in different contexts: e.g. in method, constructor, class. So you can provide more simplicity for understandability and maintainability.
- Don't use same variable for different purposes in a method, conditional etc. Create a new and different named variable instead. This is also important for maintainability and readability.
- Don't use non-ASCII chars in variable names. Those may run on your platform but may not on others.
https://google.github.io/styleguide/javaguide.html#s5-naming
Abbreviations are to be avoided, except for acronyms and certain common abbreviations
Input parameters are a special kind of local variable. They should be named much more carefully than ordinary local variables, as their names are an integral part of their method’s documentation
Type parameter names usually consist of a single letter. Most commonly it is one of these five: T for an arbitrary type, E for the element type of a collection, K and V for the key and value types of a map, and X for an exception. The return type of a function is usually R. A sequence of arbitrary types can be T, U, V or T1, T2, T3.
http://journal.stuffwithstuff.com/2016/06/16/long-names-are-long/
1. Omit words that are obvious given a variable’s or parameter’s type
2. Omit words that don’t disambiguate the name
3. Omit words that are known from the surrounding context
4. Omit words that don’t mean much of anything
http://wiki.c2.com/?GoodVariableNames
- Use complete names where an object is referenced from more than one place. Abbreviate for local scope only (for example, Enumeration e = getEnumeration()) Bad idea, use pronounceable names for all variables, is it really so tough to type "each" rather than "e", readability is more important.
- [Does using full words really improve readability for local variables' names? Is function(first, second) {return first < second;} easier to read than function(a,b) {return a < b;}, for example? (Or are there better choices than either of those?) -DavidMcLean]
- Each is readable, neither is descriptive as to what it is. What it does is. The use of complete names as indicated above was with regard to "an object .. referenced from more than one place". I take that to mean outside of local scope. Local variables are not addressable directly from outside. They may be via calling parameters however.
- I prefer names over single characters when referring to understandable by name artifacts which can acted upon by artifactories to produce other understandable by name artifacts . single characters are more readable when used in expressions like a=(x*b)+c
- example: DinnerTimeFood = function Recipe(ingredients, instructions) is more Humanly readable than is -> a = function b(c,d) -- DonaldNoyes
- [Does using full words really improve readability for local variables' names? Is function(first, second) {return first < second;} easier to read than function(a,b) {return a < b;}, for example? (Or are there better choices than either of those?) -DavidMcLean]
https://stackoverflow.com/questions/19115991/the-best-way-to-write-custom-exception-name-in-java
Instead of describing the operation that triggered the exception, it would probably be better to describe the reason: for example DuplicateUserException("can't add user because it already exists")
UserManagementException
instead of too many names, and specify the exact cause of it in some message or error code defined additionally in the class.I have found more exceptions with the form <problem><noun>Exception. For example, IllegalArgumentException. So that's what I've decided to use in the future.
https://stackoverflow.com/questions/1370840/naming-conventions-what-to-name-a-method-that-returns-a-boolean
DoStuff
), and the other returns a Boolean status and, on successful execution, the actual result via an out parameter (TryDoStuff
).TryParse
methods of various primitive types.)Try
prefix is uncommon in your language, then you probably shouldn't use it.- If no exceptions are thrown, take action A
- If (for instance) a
FileNotFoundException
is thrown, take action B - If any other exception is thrown, take action C
catch
block. If you leave it as is, you would need to change the method and the place from which the method is called, which, depending on the complexity of the project, can be in multiple locations.This time I will start with a code sample. Take a look at this:
1
2
3
| if (code.isComplexOrUnreadable()) { refactor(code); } |
Let me ask you another question then. How do you think the implementation of isComplexOrUnreadable() method looks like?
I assume that many of you would imagine something similar to this:
1
2
3
| boolean isComplexOrUnreadable() { return complex || unreadable; } |
Don’t Repeat Yourself
We repeat information about the way method was implemented. This is definitely something we should avoid.Do you remember the DRY principle? We won’t repeat the code, because if we do so, we will have to remember to update two or more places in case of any change.
What would happen if, after some time, we decided to change the implementation of the method body?
1
2
3
| boolean isComplexOrUnreadable() { return (complex || unreadable) && tests.exist(); } |
Would it be ok to leave the same name of the method? No, because the name would become misleading. The name of the method would give you invalid information.
Any change in implementation would always affect the name of the method. So in our case we would have to rename the method into something like this:
1
2
3
| boolean isComplexOrUnreadableWithTests() { return (complex || unreadable) && tests.exist(); } |
But wait! Now it is still a little bit confusing because after reading the name of the method we may have a false impression that implementation looks like that:
1
| return complex || unreadable && tests.exist(); |
Well, as you can see even kind of a “correct” name can be misleading in the situation when the name reflects implementation.
As you can see now, the name that describes HOW and not WHY can be a huge problem and can lead to other problems that degrade the quality of your code. This is not what we, as a professionals, would like to do.
To summarize, the name of the method or class that express intention of the code is a right direction, because:
- You know what place should be modified if a change is needed.
- You are not duplicating the same information (how the method was implemented).
- You are not losing information what is the reason of method/class existence.
- You know what question is answered by method’s invocation.
- It is extremely easy to reuse the code in case the same question must be asked in different place.
- You are not duplicating the code, because you simply don’t answer once again to the same question.
And at the end, this is how the code can look like if its name would express the intention:
1
2
3
| if (code.canBeImproved()) { refactor(code); } |
the name is wrong because of its direct relation to the implementation. However, this is not the only problem. The use of conjunctions in the method’s name is a sign that we could not find a right name and we just list all known things that we’ve done. It does not matter whether this list is implementation- or logic-related.
- Conjunctions - we are talking so much about Single Responsibility Principle and it is important to apply this principle when we are writing code. And aren’t conjunctions the sign that SRP is not followed? When we use words like “and” or “or”, we usually talk about more than one thing.
Whenever you spot a conjunction in the name of your variable, method or class, you should treat it as a warning. There is a strong chance that improvement is needed. - Body change leads to name change - if the change in the code does not change the whole rationale behind functionality and yet still requires changing the name of the method/class, that’s a sign that probably the name does not express the true intention.
There is more to a program than a compiler understanding what you’ve written and running the code. To create software, writing the code is one thing, maintaining the code is another. Sometimes, maintaining existing code is more difficult than creating a new one. We are afraid we may bring the project down.
- Make sure you use names that show your intentions. Names should explain what they do, why they do what they do, and how they do it.
- Endeavor to use names that carry single meaning. Do not use names that might carry very similar meanings to another thing.
- When there are differences between names, please make sure the distinction is clear.
- Ensure that names you use are easy to pronounce. Beyond communicating with the compiler, you want to be able to communicate with other developers about your project. So, use names that are easy to pronounce and reference.
- Use domain-specific namings properly. Use names that easily map to the domain in which you are working, and which also explains exactly how the naming works in that domain.
- Do not repeat namings. Ensure that not every variable you create is annotated with a certain prefix such that every name in your program has that name. This could lead to poor searching on your code.
- Endeavor to reach out more to the language you are using. Learn the vocabulary of the English language to help communicate more. The more words you know, the easier it is for you to communicate with other programmers.
Example #1: Dude, That Method Name Is Way Too Long
public static Object checkWidgetForAValidCustomerAndAccountAndContactRecord(Integer customerNumber) throws Exception
Rule of thumb: Keep your method names descriptive, but shorter rather than longer
https://skillsmatter.com/skillscasts/5747-how-to-name-things-the-solution-to-the-hardest-problem-in-programming
https://www.slideshare.net/pirhilton/how-to-name-things-the-hardest-problem-in-programming
https://news.ycombinator.com/item?id=9598527
An important rule is missing here: variables should be named with their scope in mind. So if a variable is longer lived and has larger scope its name should be that much more descriptive because when you're looking at it the only thing that will tie the value of the variable to the context within which it can be used is its name.
This factory will be an interface and will be implemented by a concrete class. What should you name them? IShapeFactory and ShapeFactory? I prefer to leave interfaces unadorned. The preceding I, so common in today’s legacy wads, is a distraction at best and too much information at worst. I don’t want my users knowing that I’m handing them an interface. I just want them to know that it’s a ShapeFactory. So if I must encode either the interface or the implementation, I choose the implementation. Calling it ShapeFactoryImp, or even the hideous CShapeFactory, is preferable to encoding the interface.
Classes and objects should have noun or noun phrase names like Customer, WikiPage, Account, and AddressParser. Avoid words like Manager, Processor, Data, or Info in the name of a class. A class name should not be a verb.
Methods should have verb or verb phrase names like postPayment, deletePage, or save. Accessors, mutators, and predicates should be named for their value and prefixed with get, set, and is according to the javabean standard
When constructors are overloaded, use static factory methods with names that describe the arguments
PICK ONE WORD PER CONCEPT
The power of variable names
PROBLEM ORIENTATION
A good mnemonic name generally speaks to the problem rather than the solution. A good name tends to express the what more than the how. In general, if a name refers to some aspect of computing rather than to the problem, it's a how rather than a what. Avoid such a name in favor of a name that refers to the problem itself.
A record of employee data could be called inputRec or employeeData. inputRec is a computer term that refers to computing ideas—input and record. employeeData refers to the problem domain rather than the computing universe. Similarly, for a bit field indicating printer status, bitFlag is a more computerish name than printerReady. In an accounting application, calcVal is more computerish than sum.
Names that are too long are hard to type and can obscure the visual structure of a program.
numTeamMembers, teamMemberCount
numSeatsInStadium, seatCount
teamPointsMax, pointsRecord
Programs with names averaging 8 to 20 characters were almost as easy to debug.
COMPUTED-VALUE QUALIFIERS IN VARIABLE NAMES
A programmer reading such a variable should be able to assume that its value isn't used outside a few lines of code
longer names are better for rarely used variables or global variables and shorter names are better for local variables or loop variables
If you modify a name with a qualifier like Total, Sum, Average, Max, Min, Record, String, or Pointer, put the modifier at the end of the name.
An exception to the rule that computed values go at the end of the name is the customary position of the Num qualifier. Placed at the beginning of a variable name, Num refers to a total: numCustomers is the total number of customers. Placed at the end of the variable name, Num refers to an index: customerNum is the number of the current customer. The s at the end of numCustomers is another tip-off about the difference in meaning. But, because using Num so often creates confusion, it's probably best to sidestep the whole issue by using Count or Total to refer to a total number of customers and Index to refer to a specific customer. Thus, customerCount is the total number of customers and customerIndex refers to a specific customer.
COMMON OPPOSITES IN VARIABLE NAMES
If a variable is to be used outside the loop, it should be given a name more meaningful than i, j, or k.
If you have several nested loops, assign longer names to the loop variables to improve readability.
many experienced programmers avoid names like i altogether.
Use positive boolean variable names. Negative names like notFound, notdone, and notSuccessful are difficult to read when they are negated
if not notFound
When naming constants, name the abstract entity the constant represents rather than the number the constant refers to.
Creating Short Names That Are Readable
Kinds of Names to Avoid
Avoid names with similar meanings.
input and inputValue, recordNum and numRecords, and fileNumber and fileIndex are so semantically similar that if you use them in the same piece of code you'll easily confuse them and install some subtle, hard-to-find errors.
Avoid names that sound similar, such as wrap and rap
Avoid variables with different meanings but similar names.
Have at least two-letter differences between names, or put the differences at the beginning or at the end. clientRecords and clientReports are better than the original names.
Avoid numerals in names
Avoid misspelled words in names.
https://dzone.com/articles/the-elements-of-modern-java-style
https://dzone.com/articles/yet-another-evil-suffix-for-object-names-client?fromrel=true
- Its scope is too broad. Since the client is an abstraction of a server, it inevitably has to represent the server's entire functionality. When the functionality is rather limited there is no issue. Take
HttpClient
from Apache HttpComponents as an example. However, when the server is more complex, the size of the client also grows. There are over 160 (!) methods inAmazonS3Client
at the time of writing, while it started with only a few dozen just a fewyearshundred versions ago. - It is data focused. The very idea of a client-server relationship is about transferring data. Take the HTTP RESTful API of the AWS S3 service as an example. There are entities on the AWS side: buckets, objects, versions, access control policies, etc., and the server turns them into JSON/XML data. Then the data comes to us and the client on our side deals with JSON or XML. It inevitably remains data for us and never really becomes buckets, objects, or versions.
- Extendability issues. Needless to say, it's almost impossible to decorate a client object when it has 160+ methods and keeps on growing. The only possible way to add new functionality to it is by creating new methods. Eventually, we get a monster class that can't be reused anyhow without modification.
Bucket
, Object
, Version
, Policy
, etc. Each of them exposes the functionality of real buckets, objects and versions, which the AWS S3 can expose.Region
, which means the entire AWS region with buckets. Then we could retrieve a bucket from it and won't need a region anymore. Then, to list objects in the bucket we ask the bucket to do it for us. No need to communicate with the entire "server object" every time, even though technically such a communication happens, of course.Github github = new RtGithub(".. your OAuth token .."); Repo repo = github.repos().get(new Coordinates.Simple("jcabi", "jcabi-github")); Issue issue = repo.issues().create("How are you?", "Please tell me..."); issue.comments().post("My first comment!");