Hướng dẫn php annotation array of objects - mảng chú thích php của các đối tượng

Tôi thích đọc và viết mã sạch - như được nêu trong "Mã sạch" của Robert C. Martin. Khi làm theo sự tín nhiệm của anh ấy, bạn không nên yêu cầu nhà phát triển [với tư cách là người dùng API của bạn] để biết cấu trúc [nội bộ] của mảng của bạn.

Người dùng API có thể hỏi: đó có phải là một mảng chỉ có một chiều không? Là các đối tượng trải rộng trên tất cả các cấp của một mảng đa chiều? Có bao nhiêu vòng lặp lồng nhau [foreach, v.v.] Tôi cần truy cập tất cả các đối tượng? Loại đối tượng nào được "lưu trữ" trong mảng đó?

Khi bạn đã phác thảo, bạn muốn sử dụng mảng đó [có chứa các đối tượng] như một mảng một chiều.

Như Nishi đã phác thảo, bạn có thể sử dụng:

/**
 * @return SomeObj[]
 */

cho điều đó.

Nhưng một lần nữa: Hãy lưu ý - đây không phải là một ký hiệu tài liệu tiêu chuẩn. Ký hiệu này được giới thiệu bởi một số nhà sản xuất IDE.

Được rồi, được rồi, với tư cách là một nhà phát triển, bạn biết rằng "[]" được gắn với một mảng trong PHP. Nhưng "cái gì đó []" có nghĩa là gì trong bối cảnh PHP bình thường? "[]" có nghĩa là: Tạo phần tử mới trong "cái gì đó". Yếu tố mới có thể là tất cả. Nhưng những gì bạn muốn thể hiện là: mảng các đối tượng có cùng loại và loại chính xác của nó. Như bạn có thể thấy, nhà sản xuất IDE giới thiệu một bối cảnh mới. Một bối cảnh mới bạn phải học. Một bối cảnh mới, các nhà phát triển PHP khác phải học [để hiểu các tài liệu của bạn]. Phong cách xấu [!].

Bởi vì mảng của bạn có một chiều mà bạn có thể muốn gọi đó là "mảng các đối tượng" là "danh sách". Xin lưu ý rằng "danh sách" có một ý nghĩa rất đặc biệt trong các ngôn ngữ lập trình khác. Ví dụ, sẽ tốt hơn nếu gọi nó là "bộ sưu tập".

Hãy nhớ rằng: bạn sử dụng ngôn ngữ lập trình cho phép bạn tất cả các tùy chọn của OOP. Sử dụng một lớp thay vì một mảng và làm cho lớp học của bạn có thể vượt qua như một mảng. Ví dụ.:

class orderCollection implements ArrayIterator

Hoặc nếu bạn muốn lưu trữ các đối tượng bên trong ở các cấp độ khác nhau trong cấu trúc mảng/đối tượng đa chiều:

class orderCollection implements RecursiveArrayIterator

Giải pháp này thay thế cho mảng của bạn bằng một đối tượng loại "OrderCollection", nhưng không cho phép hoàn thành mã trong IDE của bạn cho đến nay. Được chứ. Bước tiếp theo:

Thực hiện các phương thức được giới thiệu bởi giao diện với docblocks - đặc biệt:

/**
 * [...]
 * @return Order
 */
orderCollection::current[]

/**
 * [...]
 * @return integer E.g. database identifier of the order
 */
orderCollection::key[]

/**
 * [...]
 * @return Order
 */
orderCollection::offsetGet[]

Đừng quên sử dụng loại gợi ý loại cho:

orderCollection::append[Order $order]
orderCollection::offsetSet[Order $order]

Giải pháp này dừng lại giới thiệu rất nhiều:

/** @var $key ... */
/** @var $value ... */

Tất cả các tệp mã của bạn [ví dụ: trong vòng lặp], như Zahymaka đã xác nhận với câu trả lời của cô ấy/anh ấy. Người dùng API của bạn không bị buộc phải giới thiệu DocBlocks đó, phải hoàn thành mã. Để có @return chỉ ở một nơi làm giảm sự dư thừa [@var] càng nhiều càng tốt. Rắc "docblocks với @var" sẽ làm cho mã của bạn dễ đọc nhất.

Finaly bạn đã hoàn thành. Có vẻ khó để đạt được? Có vẻ như lấy một chiếc búa tạ để bẻ khóa một hạt? Không thực sự, vì bạn đã quen thuộc với các giao diện đó và với mã sạch. Hãy nhớ rằng: Mã nguồn của bạn được viết một lần / đọc nhiều.

Nếu mã hoàn thành IDE của bạn không hoạt động với phương pháp này, hãy chuyển sang một phương pháp tốt hơn [ví dụ: Intellij Idea, PhpStorm, NetBeans] hoặc gửi yêu cầu tính năng về trình theo dõi vấn đề của nhà sản xuất IDE của bạn.

Cảm ơn Christian Weiss [từ Đức] vì đã trở thành huấn luyện viên của tôi và đã dạy tôi một thứ tuyệt vời như vậy. Tái bút: Gặp tôi và anh ấy trên Xing.

class orderCollection implements RecursiveArrayIterator