Item 27: Return zero-length arrays, not nulls in Java

Print QR Code in Java Item 27: Return zero-length arrays, not nulls
Item 27: Return zero-length arrays, not nulls
Creating Denso QR Bar Code In Java
Using Barcode encoder for Java Control to generate, create Quick Response Code image in Java applications.
It is not uncommon to see methods that look something like this:
Bar Code Creation In Java
Using Barcode drawer for Java Control to generate, create barcode image in Java applications.
private List cheesesInStock = ; /** * @return an array containing all of the cheeses in the shop, * or null if no cheeses are available for purchase */ public Cheese[] getCheeses() { if (cheesesInStocksize() == 0) return null; }
Decode Barcode In Java
Using Barcode decoder for Java Control to read, scan read, scan image in Java applications.
Effective Java: Programming Language Guide
QR-Code Creator In Visual C#
Using Barcode maker for VS .NET Control to generate, create QR-Code image in Visual Studio .NET applications.
There is no reason to make a special case for the situation where no cheeses are available for purchase Doing so requires extra code in the client to handle the null return value, for example:
QR Generation In Visual Studio .NET
Using Barcode encoder for ASP.NET Control to generate, create QR Code image in ASP.NET applications.
Cheese[] cheeses = shopgetCheeses(); if (cheeses != null && ArraysasList(shopgetCheeses())contains(CheeseSTILTON)) Systemoutprintln("Jolly good, just the thing");
Quick Response Code Generation In .NET
Using Barcode encoder for .NET Control to generate, create QR image in VS .NET applications.
instead of:
Making QR-Code In Visual Basic .NET
Using Barcode encoder for VS .NET Control to generate, create Denso QR Bar Code image in .NET applications.
if (ArraysasList(shopgetCheeses())contains(CheeseSTILTON)) Systemoutprintln("Jolly good, just the thing");
Bar Code Creator In Java
Using Barcode generator for Java Control to generate, create barcode image in Java applications.
This sort of circumlocution is required in nearly every use of a method that returns null in place of a zero length array It is error prone, as the programmer writing the client might forget to write the special-case code to handle a null return Such an error may go unnoticed for years, as such methods usually return one or more objects Less significant, but still worthy of note, returning null in place of a zero length array also complicates the arrayreturning method itself It is sometimes argued that a null return value is preferable to a zero-length array because it avoids the expense of allocating the array This argument fails on two counts First, it is inadvisable to worry about performance at this level unless profiling has shown that the method in question is a real contributor to performance problems (Item 37) Second, it is possible to return the same zero-length array from every invocation that returns no items because zero-length arrays are immutable and immutable objects may be shared freely (Item 13) In fact, this is exactly what happens when you use the standard idiom for dumping items from a collection into a typed array:
Printing Code 128 Code Set C In Java
Using Barcode generator for Java Control to generate, create Code 128C image in Java applications.
private List cheesesInStock = ; private final static Cheese[] NULL_CHEESE_ARRAY = new Cheese[0]; /** * @return an array containing all of the cheeses in the shop */ public Cheese[] getCheeses() { return (Cheese[]) cheesesInStocktoArray(NULL_CHEESE_ARRAY); }
Making Code39 In Java
Using Barcode generator for Java Control to generate, create Code 3 of 9 image in Java applications.
In this idiom, a zero-length array constant is passed to the toArray method to indicate the desired return type Normally the toArray method allocates the returned array, but if the collection is empty, it fits in the input array, and the specification for CollectiontoArray(Object[]) guarantees that the input array will be returned if it is large enough to hold the collection Therefore the idiom never allocates a zero-length array but instead reuses the type-specifier constant In summary, there is no reason ever to return null from an array-valued method instead of returning a zero-length array This idiom is likely a holdover from the C programming
Generating EAN-13 In Java
Using Barcode printer for Java Control to generate, create EAN13 image in Java applications.
Effective Java: Programming Language Guide
Barcode Drawer In Java
Using Barcode generator for Java Control to generate, create barcode image in Java applications.
language, in which array lengths are returned separately from actual arrays In C, there is no advantage to allocating an array if zero is returned as the length
Leitcode Drawer In Java
Using Barcode drawer for Java Control to generate, create Leitcode image in Java applications.
Item 28: Write doc comments for all exposed API elements
Data Matrix Encoder In .NET
Using Barcode encoder for ASP.NET Control to generate, create DataMatrix image in ASP.NET applications.
If an API is to be usable, it must be documented Traditionally API documentation was generated manually, and keeping documentation in sync with code was a big chore The Java programming environment eases this task with a utility called Javadoc This utility generates API documentation automatically from source code in conjunction with specially formatted documentation comments, more commonly known as doc comments The Javadoc utility provides an easy and effective way to document your APIs, and its use is widespread If you are not already familiar with the doc comment conventions, you should learn them While these conventions are not part of the Java programming language, they constitute a de facto API that every programmer should know The conventions are defined The Javadoc Tool Home Page [Javadoc-b] To document your API properly, you must precede every exported class, interface, constructor, method, and field declaration with a doc comment, subject to one exception discussed at the end of this item In the absence of a doc comment, the best that Javadoc can do is to reproduce the declaration as the sole documentation for the affected API element It is frustrating and error-prone to use an API with missing documentation comments To write maintainable code, you should also write doc comments for unexported classes, interfaces, constructors, methods, and fields The doc comment for a method should describe succinctly the contract between the method and its client With the exception of methods in classes designed for inheritance (Item 15), the contract should say what the method does rather than how it does its job The doc comment should enumerate all of the method's preconditions, which are the things that have to be true in order for a client to invoke it, and its postconditions, which are the things that will be true after the invocation has completed successfully Typically, preconditions are described implicitly by the @throws tags for unchecked exceptions; each unchecked exception corresponds to a precondition violation Also, preconditions can be specified along with the affected parameters in their @param tags In addition to preconditions and postconditions, methods should document any side effects A side effect is an observable change in the state of the system that is not obviously required to achieve the postcondition For example, if a method starts a background thread, the documentation should make note of it Finally, documentation comments should describe the thread safety of a class, as discussed in Item 52 To describe its contract fully, the doc comment for a method should have a @param tag for every parameter, a @return tag unless the method has a void return type, and a @throws tag for every exception thrown by the method, whether checked or unchecked (Item 44) By convention the text following a @param tag or @return tag should be a noun phrase describing the value represented by the parameter or return value The text following a @throws tag should consist of the word if, followed by a noun phrase describing the conditions under which the exception is thrown Occasionally, arithmetic expressions are used in place of noun phrases All of these conventions are illustrated in the following short doc comment, which comes from the List interface:
Data Matrix ECC200 Printer In VB.NET
Using Barcode generation for VS .NET Control to generate, create ECC200 image in .NET applications.
Effective Java: Programming Language Guide /** * Returns the element at the specified position in this list * * @param index index of element to return; must be * nonnegative and less than the size of this list * @return the element at the specified position in this list * @throws IndexOutOfBoundsException if the index is out of range * (<tt>index < 0 || index >= thissize()</tt>) */ Object get(int index)
Print ANSI/AIM Code 39 In VS .NET
Using Barcode creation for Visual Studio .NET Control to generate, create ANSI/AIM Code 39 image in .NET applications.
Notice the use of HTML metacharacters and tags in this doc comment The Javadoc utility translates doc comments into HTML, and arbitrary HTML elements contained in doc comments end up in the resulting HTML document Occasionally programmers go so far as to embed HTML tables in their doc comments, although this is uncommon The most commonly used tags are <p> to separate paragraphs; <code> and <tt>, which are used for code fragments; and <pre>, which is used for longer code fragments The <code> and <tt> tags are largely equivalent The <code> tag is more commonly used and, according to the HTML 401 specification, is generally preferable because <tt> is a font style element (The use of font style elements is discouraged in favor of style sheets [HTML401]) That said, some programmers prefer <tt> because it is shorter and less intrusive Don't forget that escape sequences are required to generate HTML metacharacters, such as the less than sign (<), the greater than sign (>), and the ampersand (&) To generate a less than sign, use the escape sequence < To generate a greater than sign, use the escape sequence > To generate an ampersand, use the escape sequence & The use of escape sequences is demonstrated in the @throws tag of the above doc comment Finally, notice the use of word this in the doc comment By convention, the word this always refers to the object on which the method is invoked when it is used in the doc comment for an instance method The first sentence of each doc comment becomes the summary description of the element to which the comment pertains The summary description must stand on its own to describe the functionality of the entity it summarizes To avoid confusion, no two members or constructors in a class or interface should have the same summary description Pay particular attention to overloadings, for which it is often natural to use the same first sentence in a prose description Be careful not to include a period within the first sentence of a doc comment If you do, it will prematurely terminate the summary description For example, a documentation comment that began with A college degree, such as BS, MS, or PhD would result in a summary description of A college degree, such as B The best way avoid this problem is to avoid the use of abbreviations and decimal fractions in summary descriptions It is, however, possible to include a period in a summary description by replacing the period with its numeric encoding, . While this works, it doesn't make for pretty source code:
Painting Bar Code In Visual Basic .NET
Using Barcode generation for VS .NET Control to generate, create bar code image in VS .NET applications.
Effective Java: Programming Language Guide /** * A college degree, such as B.S., M.S. or * Ph.D */ public class Degree { }
Data Matrix Maker In Visual C#.NET
Using Barcode maker for Visual Studio .NET Control to generate, create Data Matrix ECC200 image in VS .NET applications.
It is somewhat misleading to say that the summary description is the first sentence in a doc comment Convention dictates that it should seldom be a complete sentence For methods and constructors, the summary description should be a verb phrase describing the action performed by the method For example,
Barcode Generation In VS .NET
Using Barcode generation for ASP.NET Control to generate, create bar code image in ASP.NET applications.
Code 39 Extended Printer In VB.NET
Using Barcode encoder for .NET Control to generate, create Code 39 image in VS .NET applications.