Nhận xét đơn giản của Getter / Setter

Bạn sử dụng quy ước nào để nhận xét getters và setters? Ví dụ: đây là điều mà tôi đã tự hỏi khá lâu:

/**
 * (1a) what do you put here?
 * @param salary (1b) what do you put here?
 */
public void setSalary(float salary);

/*
 * (2a) what do you put here?
 * @return (2b)
 */
public float getSalary();

Tôi luôn thấy mình viết khá nhiều điều giống hệt nhau cho 1a / b và 2a / b, đại loại như 1a) Đặt mức lương của nhân viên, 1b) mức lương của nhân viên. Nó chỉ có vẻ quá thừa. Bây giờ tôi có thể thấy đối với một cái gì đó phức tạp hơn, bạn có thể viết nhiều hơn trong phần (a), để cung cấp ngữ cảnh, nhưng đối với phần lớn các getters / setters ngoài kia, cách diễn đạt gần như giống hệt nhau.

Tôi chỉ tò mò nếu, đối với getters / setters đơn giản, có thể chỉ điền vào phần (a) HOẶC phần (b).

Bạn nghĩ sao?

Tôi thường chỉ điền phần tham số cho setters và phần @return cho getters:

/**
 * 
 * @param salary salary to set (in cents)
 */
public void setSalary(float salary);

/**
 * @return current salary (in cents, may be imaginary for weird employees)
 */
public float getSalary();

Bằng cách đó, các công cụ kiểm tra javadoc (chẳng hạn như cảnh báo của Eclipse) sẽ xuất hiện rõ ràng và không có sự trùng lặp.

Hoàn toàn vô nghĩa - bạn tốt hơn hết nếu không có loại mã này làm lộn xộn mã của bạn:

/**
 * Sets the foo.
 * 
 * @param foo the foo to set
 */
public void setFoo(float foo);

Rất hữu ích, nếu được bảo hành:

/**
 * Foo is the adjustment factor used in the Bar-calculation. It has a default
 * value depending on the Baz type, but can be adjusted on a per-case base.
 * 
 * @param foo must be greater than 0 and not greater than MAX_FOO.
 */
public void setFoo(float foo);

Đặc biệt là việc giải thích ý nghĩa thực sự của thuộc tính có thể rất quan trọng trong các mô hình miền. Bất cứ khi nào tôi nhìn thấy một hạt đậu có đầy đủ các thuộc tính với những cái tên khó hiểu mà chỉ các chủ ngân hàng đầu tư, nhà hóa sinh hoặc nhà vật lý lượng tử mới hiểu và các bình luận giải thích rằng phương thức setGobbledygook () "thiết lập gobbledygook", tôi muốn bóp cổ ai đó.

Nói chung là không có gì, nếu tôi có thể giúp nó. Getters và setters phải tự giải thích.

Tôi biết điều đó nghe có vẻ không phải câu trả lời, nhưng tôi cố gắng sử dụng thời gian của mình để bình luận những điều cần giải thích.

Tôi muốn nói rằng chỉ lo lắng về việc nhận xét getters và setters nếu chúng có một số loại tác dụng phụ hoặc yêu cầu một số loại điều kiện tiên quyết bên ngoài quá trình khởi tạo (ví dụ: get sẽ xóa một mục khỏi cấu trúc dữ liệu hoặc để thiết lập thứ gì đó bạn cần để có x và y ở vị trí đầu tiên). Nếu không, các ý kiến ​​ở đây là khá thừa.

Chỉnh sửa: Ngoài ra, nếu bạn thấy có nhiều tác dụng phụ liên quan đến getter / setter của mình, bạn có thể muốn thay đổi getter / setter để có một tên phương thức khác (nghĩa là: đẩy và bật cho một ngăn xếp) [Cảm ơn vì bình luận bên dưới]

Hãy tự hỏi bản thân xem bạn muốn mọi người thấy gì khi nhận xét được xem dưới dạng JavaDocs (từ trình duyệt). Nhiều người nói rằng tài liệu là không cần thiết vì đó là điều hiển nhiên. Điều này sẽ không giữ nếu trường là riêng tư (trừ khi bạn bật JavaDocs cho các trường riêng tư một cách rõ ràng).

Trong trường hợp của bạn:

public void setSalary(float s)
public float getSalary()

Không rõ lương được thể hiện bằng gì. Nó là xu, đô la, bảng Anh, RMB?

Khi lập tài liệu setters / getters, tôi muốn tách những gì ra khỏi bảng mã. Thí dụ:

/**
 * Returns the height.
 * @return height in meters
 */
public double getHeight()

Dòng đầu tiên cho biết nó trả về chiều cao. Tham số trả về ghi lại chiều cao tính bằng mét.

Tại sao họ không chỉ bao gồm một thẻ tham chiếu để cho phép bạn nhận xét giá trị trường và tham chiếu từ getters và setters.

/**
* The adjustment factor for the bar calculation.
* @HasGetter
* @HasSetter
*/
private String foo;

public String getFoo() {
  return foo;
}

public void setFoo() {
  this foo = foo;
}

Để tài liệu áp dụng cho getter và setter cũng như trường (nếu javadocs riêng được bật thì đó là).

Bạn có thể tránh được loại bảng ghi này bằng cách sử dụng Project Lombok . Chỉ cần ghi lại biến trường, ngay cả khi nó là private, và để các chú thích của Lombok tạo ra các getters và setters được lập tài liệu đúng cách.

Đối với tôi, lợi ích này chỉ là giá trị chi phí .

Tôi thực sự thất vọng về các câu trả lời về cơ bản nói rằng việc lập tài liệu toàn diện là một sự lãng phí thời gian. Làm thế nào mà các khách hàng của API của bạn phải biết rằng một phương thức được gọi setXlà bộ thiết lập thuộc tính JavaBean tiêu chuẩn trừ khi bạn nói rõ ràng như vậy trong tài liệu ?

Nếu không có tài liệu hướng dẫn, người gọi sẽ không biết phương pháp này có tác dụng phụ gì không, ngoại trừ việc họ khoanh tay về quy ước rõ ràng đang được tuân thủ.

Tôi chắc rằng mình không phải là người duy nhất ở đây gặp bất hạnh khi tìm ra cách khó mà một phương thức được gọi là setXkhông chỉ đặt một thuộc tính.

Nếu không có thao tác đặc biệt nào trong getter / setter, tôi thường viết:

Với Javadoc (với tùy chọn riêng tư):

/** Set {@see #salary}. @param {@link #salary}. */
public void setSalary(float salary);

và / hoặc

/** 
 * Get {@see #salary}.
 * @return {@link #salary}.
 */
public float salary();

Với Doxygen (với tùy chọn trích xuất riêng tư):

/** @param[in] #salary. */
public void setSalary(float salary);

/** @return #salary. */
public float salary();

Nhận xét người truy cập, đặc biệt nếu họ không thực hiện bất kỳ thao tác nào ở bất kỳ đâu, là không cần thiết và lãng phí đầu ngón tay.

Nếu ai đó đọc mã của bạn không thể hiểu được person.getFirstName()trả lại tên đầu tiên của một người, bạn nên thử mọi cách trong khả năng của mình để đuổi anh ta. Nếu nó thực hiện một số phép thuật cơ sở dữ liệu, ném một vài con xúc xắc, gọi Thư ký của Tên để lấy tên đầu tiên, Thật an toàn khi cho rằng đó là một hoạt động không tầm thường và ghi lại nó tốt.

Mặt khác, nếu bạn person.getFirstName()không trả lại tên của một người ... thì, chúng ta đừng đến đó, phải không?

Đừng đặt bất cứ điều gì nếu tên trường mô tả thành thạo nội dung.

Nói chung, hãy để mã tự đứng và tránh bình luận nếu có thể. Điều này có thể yêu cầu cấu trúc lại.

CHỈNH SỬA: Ở trên chỉ đề cập đến getters và setters. Tôi tin rằng bất cứ điều gì không tầm thường nên được javadoc'ed đúng cách.

bạn có thể điền vào phần (b), đặc biệt nếu bạn đặt một chú thích ở phần khai báo trường cho biết nội dung của trường.

Nếu javadoc không thêm bất cứ điều gì, tôi xóa javadoc và sử dụng các bình luận được tạo tự động.

Tôi luôn điền vào cả hai. Thời gian bổ sung dành cho việc đánh máy là không đáng kể và nhìn chung thì nhiều thông tin hơn là ít hơn.