Các kiểu đánh dấu docblock có thừa khi sử dụng kiểu gõ nghiêm ngặt

Tôi có một codebase riêng khá lớn đã phát triển được khoảng mười năm nay. Tôi không sử dụng phpDocumentor nhưng vì việc sử dụng các phần docblock đã trở thành tiêu chuẩn trong các dự án nguồn mở, tôi cũng đã áp dụng cách viết docblocks cho tất cả các phương thức công khai trong kho lưu trữ của mình. Hầu hết các khối chỉ chứa một mô tả nhỏ và các kiểu chữ cho tất cả các tham số và kiểu trả về.

Với sự xuất hiện của phân tích tĩnh, những kiểu chữ này đã giúp tôi rất nhiều trong việc tìm kiếm sự không nhất quán và các lỗi có thể xảy ra. Gần đây tôi đã chuyển đổi toàn bộ cơ sở mã (Hiện đang chạy trên PHP7.2) để có tất cả các tham số và trả về các giá trị được gợi ý nếu có thể, sử dụng các kiểu chữ của PHP. Và bây giờ tôi đang tự hỏi ... Không phải những kiểu đánh dấu docblock này là dư thừa sao? Nó yêu cầu khá nhiều công việc để giữ cho tất cả các tài liệu được đồng bộ hóa với mã thay đổi liên tục và vì chúng không thêm bất kỳ thông tin mới nào, tôi tự hỏi liệu có nên loại bỏ hoàn toàn chúng hay không.

Trong một mặt, loại bỏ tài liệu cảm thấy xấu, ngay cả khi nó là dư thừa. Mặt khác, tôi thực sự cảm thấy muốn phá vỡ các công cụ gợi ý loại hàng ngày không tự lặp lại theo nguyên tắc đã được gợi ý.

Thông tin có thể được tìm thấy trong mã không nên được sao chép trong các bình luận.

Tốt nhất, thật lãng phí nỗ lực để giữ cho chúng được đồng bộ hóa. Nhiều khả năng, cuối cùng họ sẽ thoát khỏi sự đồng bộ. Tại thời điểm đó, họ chỉ là khó hiểu.

Nếu bạn nhìn vào tương đương DocBlock bằng các ngôn ngữ được nhập tĩnh (ví dụ: Java, C #), bạn sẽ thấy rằng các nhận xét tài liệu không chứa thông tin loại. Trong trường hợp như đây là trường hợp trong mã PHP của bạn, tôi thực sự khuyên bạn nên làm theo. Tất nhiên, khi gợi ý loại không thể được áp dụng, một bình luận vẫn là lựa chọn tốt nhất của bạn.

Điều này không liên quan đến PHP, nhưng thông tin loại trùng lặp có thể có ý nghĩa khi loại được ngầm hiểu (ví dụ Haskell).

Có, docblocks đã trở nên dư thừa với php 7.

Hầu hết thời gian trong mã hóa là dành cho việc đọc, vì vậy việc phải đọc cùng một thứ hai lần ảnh hưởng đến năng suất của bạn. Hơn nữa, nó làm cho nó dễ dàng bỏ lỡ những bình luận thực sự quan trọng.

Tôi không viết docblocks nữa, trừ khi tôi muốn gõ gợi ý một mảng thuộc một loại nhất định (ví dụ @return int[]hoặc @param SomeStatus[] $statusList) hoặc khi tôi muốn thêm nhận xét về phương thức, tham số hoặc giá trị trả về. Tôi thấy điều quan trọng là phải vô hiệu hóa kiểm tra phpstorm kích hoạt khi bạn không có các tham số alle và trả về các loại trong docblock nếu bạn có docblock.

Mã và tài liệu thường có các đối tượng khác nhau: tài liệu dành cho người dùng chức năng đó. Họ không cần phải nhìn vào mã để hiểu các loại. Do đó, tài liệu nên bao gồm tất cả các thông tin cần thiết, bao gồm các loại.

Trong một số hệ thống, không cần thiết phải chỉ định loại tham số trong tài liệu vì loại có thể được lấy từ mã. PHPDoc không phải là một hệ thống như vậy. Thay vào đó, @paramthẻ được ghi lại rằng

Khi được cung cấp, PHẢI chứa Loại để cho biết những gì được mong đợi

Người dùng khá nhiều công việc để giữ cho tất cả các tài liệu được đồng bộ hóa với mã đang thay đổi, phần nào bị giảm đi vì PHPDoc sẽ kiểm tra các gợi ý về loại tài liệu đối với các gợi ý về loại mã. Đây là một loại phân tích linting / tĩnh, vì vậy hãy tạo tài liệu của bạn tạo một phần của đường ống kiểm tra tự động của bạn.

Một câu hỏi khác mà bạn có thể muốn tự hỏi mình là tại sao các chức năng này được ghi lại trong chi tiết này khi chúng đang thay đổi. Động lực thông thường là tạo ra một hướng dẫn tham khảo HTML về các giao diện của bạn. Nhưng nếu tài liệu không bao giờ được đọc bên ngoài IDE hoặc nếu bạn không có giao diện ổn định trong đó tài liệu có ý nghĩa, thì các tài liệu chi tiết là không cần thiết hoặc thậm chí sai lệch. Có thể tốt hơn là chỉ viết một bản tóm tắt và trì hoãn các tài liệu đầy đủ cho đến khi bạn đạt đến một thiết kế ổn định.