Library System 源码带你了解javadoc注释的规范使用，了解项目分析过程【Coding improve】

图书馆管理系统----规范，正确学习建立项目（SE）

之前的项目有一个地方没有达到规范，那就是注解，javadoc注解非常方便，所以我们要合理的，正确地使用javadoc注解
看一下部分截图

读者类的javadoc注释

在真正要自己完整实现一个项目，首先要进行的是分析，要进行UML设计，看能否实现功能，首先就是分析需求文档，从文档中找出类，找出属性。找出关系，设计类的方法。写一个驱动类来测试。我们每写一个类，都需要进行测试，防止影响之后的类的建立，这里我将需求给敲出来

The Requirement【the specification of the system】

先说一点，确实要学好英语，因为这关系到变量命名，以及后面查询关键技术可能会进入英文网站，掌握一些常用词语

	The library system tracks the items checked out by borrowers. The system contains a catalog of the items owned by the library. There are two kinds of catalog items : books and recording. All catalog items are identified by a unique code. (If the library owns several copies of the same book or recording, each copy has a unique code.) The information for each item includes title,year,and avaliability, An item is available if it is not checked out.
	In addition:
	(1) . The information for a book includes the author and number of pages.
	(2) . The informaton for a recording includes the performer and format(CD or tape)
	The system contains a database of the brrowers. Each brrower has a unique identification code in addition to a name. The system maintains a list, for each borrower, of the catalog items checked out.
	In the library system, the user should be able to:
	1 . Display the catalog by listing the code , title ,and availablity of each item.
	2 . Display a catalog item.
	3 . Display the borrowers by listing the identification code and name of each borrower.
	4 . Display the catalog items checked out by a borrower.
	5 . Check out a catalog item by adding the item to borrower's list of borrowed items.
	6 . Check in a catalog item by removing the item from borrower's list of borrowed items.

这里的需求很简单，首先我们找出所有的名词，然后进行适当的删减得到一个名词表

这里我大概写了一下，大家可以具体去看我的第三篇博客—UML实战来学习如何建模

analysis

这里我们首先可以发现CatalogItem, Book ,Recording三个类，后两个继承前者 ，在原有属性上增加了属性， 还有Borrower类 关联的是管理其的DataBase, 下面有几个属性，其中有一个属性为CatalogItemList，换一个单词就是BorrowedItems,这也是一个操作的类，包括增删等操作；还有就是管理所有CatalogItem的Catalog类，也就是一个集合结构

下面就是绘制UML类图了

这里使用mermaid语言来绘制类图

这里给大家看一下编写的源码

这里我习惯于先写出每个类的关联关系，之后再写出每一个类，这里把上面分析的7个类建立完成之后，我们一般会设计一个驱动类，来实现代码的复用

CatalogItem <|--Book
CatalogItem <|-- Recording
LibrarySystem-->"1"Catalog
LibrarySystem-->"1"BorrowerDatabase
Catalog -->"1..*"CatalogItem
Borrower -->"1"BorroweredList
BorroweredList-->"1..*"CatalogItem
BorrowerDataBase-->"1..*"Borrower
class LibrarySystem{
+displayCatalog()
+dispalyCatalogItem()
+displayBorrowerDB()
+displayBorrower()
+CheckIn()
+CheckOut()
}
class Catalog{
+addItem(item:CatalogItem)
+removeItem(item:CatalogItem):CatalogItem
+getItem(code: String):CatalogItem
+getItem(index:int):CatalogItem
+getNumberOfItems():int
+DiapalyCatalog()
}
class CatalogItem{
-code:String
-title: String
-year:int
-availability: boolean
+getCode():String
+getTitle():String
+getYear():int
+isAvailavle():boolean
+setAvaliability(statu:boolean)
+displayCatalogItem()
}

这里就设计一个类LibrarySystem, 类方法就是用户所要求是实现的核心功能displayCatalog(),dispalyCatalogItem(),displayBorrowerDB(),displayBorrower(),chekIn(),checkOut()

接下来，我么就要在类图上分析看是否能够实现功能，操作关联的两个属性，比如第一个显示目录功能

//这里关联了Catalog
for(int i = 0; i < catalog.getNumberOfItems(); i++)
{
	Item item = catalog.getItem(i);
    .....
    item.getCode();//是可以显示的
}

这里因为是以图书馆的管理人员来运行的，这里因为对其的操作就是所有类的方法，这里我们就不对其进行分包了，因为这里的项目简单，都只建立一个包

Coding

这次我写这个更小的项目的目的只是为了进一步规范操作，比如命名，最主要的是要就是javadoc注释的使用，之前的项目中对于这个内容使用的不是很规范，这次每一个类都会规范使用注释。

需要注意的就是对于注释的使用，一些复杂的方法，和每一个类的前面都应该加上注释，甚至说每一个方法前面都可以加上注释，注释不是简单阐述函数的功能，还应该表明param和return，对于表还要使用link结构

Catalog

这里我们先来写一下Catalog类，不仅要在类前面写注释，在每个方法前面都需要写注释，Catalog类关联了catalogItem，并且数量多，为容器类，并且因为是要实现随机存取，综合来看，使用ArrayList而不是LinkedList，这里的addItem方法就是调用容器类的add方法

该类中有两个地方需要注意，第一个就是equals方法中，传入的是一个普通对象，所以首先要判断该对象是否是CatalogItem及其子类的实例，再进行向下转型；第二个就是dispaly中，for-each循环中，使用三目运算符来简化代码

CatalogItem

编码原则为面向超类编程，所以我们在考虑一个类建立为普通类，或者是抽象类的时候，就首先看有没有实际的意义，图书馆中有book，recording，但是没有具体的对象就是CatalogITem，所以这里应该建立为抽象类，好处就是可以约束programmer不能直接创建catalogIten对象

抽象类中不一定有抽象方法，只要加了abstract修饰，就不能直接创建一个CatalogItem对象，只能为子类对象

规范的代码【javadoc注释】

给大家展示一部分类

Catalog

package CfengLibrary;

import java.util.ArrayList;
import java.util.Iterator;

/**
 * Maintains the information of a library catalog.Contain
 * collections of objects(@link catalogItem)
 * @author Cfeng
 * @version 1.0.0
 * @see CatalogItem //实现连接跳转，这里是一个容器类
 */
public class Catalog implements Iterable<CatalogItem> {
	// Collection of <code>catalogItem</code> objects
	private ArrayList<CatalogItem>  items;
	/**
	 * constructs an empty catalog
	 */
	public Catalog() {
		this.items = new ArrayList<>();
	}
	/**
	 * Add a object(@link catalogItem) to this catalog
	 * @param CatalogItem  the object(@link CatalogItem)
	 */
	public void addItem(CatalogItem catalogItem) {
		this.items.add(catalogItem);
	}
	/**
	 * Remove a object(@link catalogItem) to this catalog
	 * @param CatalogItem  the object(@link CatalogItem)
	 */
	public void removeItem(CatalogItem catalogItem) {
		this.items.remove(catalogItem);
	}
	
	/**
	 * get the itreator of the container({@link Catalog}
	 */
	@Override
	public Iterator<CatalogItem> iterator() {
		return this.items.iterator();
	}
	/**
	 * Return the {@link CatalogItem} object with the specified
	 * <code>code</code>
	 * @param code the code of an item
	 *@return The {@link CatalogItem} object with the specified
	 *		code. Returns <code>null</code> if the object with
	 *		the code is not found
	 */
	public CatalogItem getItem(String code) {
		for(CatalogItem catalogItem : this.items) {
			if(catalogItem.getCode().equals(code)) {
				return catalogItem;
			}
		}
		return null;
	}
	/**
	 * Return the {@link CatalogItem} object with the specified
	 * <code>index</code>
	 * @param index the index of an item
	 *@return The {@link CatalogItem} object with the specified
	 *		code. Returns <code>null</code> if the object with
	 *		the code is not found
	 */
	public CatalogItem getItem(int index) {
		return this.items.get(index);
	}
	
	/**
	 * Return the number of items in the catalog
	 * @return the number of {@link CatalogItem} objects in the catalog
	 */
	public int getNumberOfItems() {
		return this.items.size();
	}
	/**
	 * Display the Catalog
	 */
	public void displayCatalog() {
		System.out.println("------------system--------------Fly Library--------------------system--------------");
		if(this.getNumberOfItems() == 0) {
			System.out.println("The catalog is empty");
		} else {
			for(CatalogItem item : this.items) {
				System.out.println(item.toString());
			}
		}
		System.out.println("------------system--------------Fly Library--------------------system--------------");
	}
	
}
//去看java的源码就可以发现注释非常多

CatalogItem

这个类加一个abstract关键字修饰一下，这样就可以提醒programmer不要直接实例化这个对象，因为没有意义

package CfengLibrary;
/**
 * Describe CatalogItem in code
 */
public abstract class CatalogItem {
	/*Code of this catalogItem*/
	private String code;
	
	/*Title of this catalogItem*/
	private String title;
	
	/*Year of this catalogItem*/
	private int year;
	
	/*Availability of this catalogItem*/
	private boolean avaliable;
	/**
	 * constructs a full CatalogItem
	 */
	public CatalogItem(String code, String title, int year, boolean avaliable) {
		this.code = code;
		this.title = title;
		this.year = year;
		this.avaliable = avaliable;
	}
	/**
	 * Get the code of the CatalogItem Object
	 * @return  the code of the CatalogItem Object
	 */
	public String getCode() {
		return this.code;
	}
	/**
	 * Get the title of the CatalogItem object
	 * @return the title of the CatalogItem Object
	 */
	public String getTitle() {
		return this.title;
	}
	/**
	 * Get the year of the CatalogItem object
	 * @return the year of the CatalogItem object
	 */
	public int getYear() {
		return this.year;
	}
	/**
	 * Return <code>true</code> if the item is available
	 * @return <code>true</code> if the item is available
	 * 			<code>false</code> otherwise
	 */
	public boolean isAvailable() {
		return this.avaliable;
	}
	/**
	 * Set the availability of the CatalogItem object
	 * @param value the new availability of the object
	 */
	public void setAvailability(boolean value) {
		this.avaliable = value;
	}
	/**
	 * Return true if the object equals to this catalogItem
	 * @param obj if obj is the instantiation of CatalogItem, then compare with this catalogItem
	 * @return <code>true</code> if the object equals to this catalogItem
	 */
	@Override
	public boolean equals(Object obj) {
		return obj instanceof CatalogItem && this.getCode().equals(((CatalogItem)obj).getCode());
	}
	/**
	 * Return this catalogItem's string representation
	 * @return this catalogItem's string representation
	 */
	@Override
	public String toString() {
		return getCode() + "\t" + getTitle() + "\t" + getYear() + "\t" + (isAvailable()?"(A)":"(NA)");
	}
}

Book

package CfengLibrary;
/**
 * Describe Book in code
 * Book extends CatalogItem
 */
public class Book extends CatalogItem {
	/*Author of the Book*/
	private String author;
	
	/*Number of pages in the bool*/
	private int numberOfPage;
	/**
	 * Constructs a <code>Book</code> object.
	 * @param all the attributes:super,author,numberOfPage
	 */
	public Book(String code, String title, int year, boolean avaliable, String author, int numberOfPage) {
		super(code, title, year, avaliable);
		this.author = author;
		this.numberOfPage = numberOfPage;
	}
	/**
	 *  Return the author of this book
	 *  
	 *  @return the author of this book
	 */
	public String getAthor() {
		return this.author;
	}
	/**
	 * Return the number of pages of this book
	 * 
	 * @return the number of pages of this book
	 */
	public int getNumberOfPages() {
		return this.numberOfPage;
	}
	/**
	 * Return the String representation of this book
	 * 
	 *  @return the String representation of this book
	 */
	@Override
	public String toString() {
		return super.toString() + "\t" + getAthor() + "\t" + getNumberOfPages();
	}
}

Borrower

package CfengLibrary;
/**
 * This class models a library user
 * @author Cfeng
 * @see BrrowedList
 * @see CatalogItem
 */
public class Borrower {
	/* Identification number of the borrower */
	private String id;
	
	/* Name of the borrower*/
	private String name;
	
	/* Items checked out by the borrower*/
	private BorroweredList borroweredList;
	/**
	 * Constructs a <code>Borrower</code> object
	 * <p>
	 * The collection of the borrowed item is initially empty.
	 * <p>
	 * @param id, name
	 */
	public Borrower(String id, String name) {
		this.id = id;
		this.name = name;
		this.borroweredList = new BorroweredList();
	}
	/**
	 * Returns the identification of this borrower
	 * 
	 * @return he identification of this borrower
	 */
	public String getId() {
		return this.id;
	}
	/**
	 * Returns the name of this borrower
	 * 
	 * @return the name of this borrower
	 */
	public String getName() {
		return this.name;
	}
	/**
	 * Return the borrowered items collection
	 * 
	 * @return a {@link BorroweredList} object
	 */
	public BorroweredList getBorroweredList() {
		return this.borroweredList;
	}
}

这次的非常简单的代码主要就是为了展示写一个项目的一个分析的过程，不是说看到需求就可以马上编码，还有就是要正确规范使用javadoc注释，这是很重要的一个point.