Tài liệu chúng tôi sẽ tạo mô tả giao diện của mã nhiều hơn chi tiết nhỏ về việc triển khai thực tế. Ví dụ: bạn có thể ghi lại một API mà bạn đã phát triển cho thế giới bên ngoài để tương tác với một số dự án cực kỳ quan trọng mà bạn đang làm việc.
Có một API là điều tuyệt vời, nhưng đối với các nhà phát triển khác để nhanh chóng có được cái nhìn tổng quan về các khả năng của API và có thể tạo ra mã hoạt động trong một khoảng thời gian ngắn thì điều đó thậm chí còn tốt hơn. Nếu bạn tuân theo các quy ước thích hợp trong khi viết mã, tất cả những gì bạn phải làm là chạy một tiện ích để trích xuất và định dạng tài liệu từ mã
Ngay cả khi bạn không mời cả thế giới tương tác với phần mềm của mình, các nhà phát triển trong nhóm của bạn sẽ được hưởng lợi từ tài liệu mô tả một số lớp cốt lõi đang được sử dụng trong suốt dự án. Chỉ cần tưởng tượng đọc mã của đồng nghiệp của bạn và bắt gặp một số phiên bản đối tượng hoặc lệnh gọi phương thức không thể giải mã được. Sẽ không tuyệt sao nếu chỉ cần lấy tài liệu API cho đối tượng đó và đọc về cách sử dụng, thuộc tính và phương thức của nó? . Theo cách đó, nhà phát triển không chỉ tìm hiểu về một lớp cụ thể mà còn về mối quan hệ của nó với các lớp khác. Theo một cách nào đó, nó sẽ cho phép lập trình viên hình thành một bức tranh cấp cao về cách các phần khác nhau khớp với nhau.
Một lý do khác để xem xét tài liệu cấp mã là mã nguồn có thể truy cập dễ dàng do PHP là ngôn ngữ kịch bản. Trừ khi họ chọn mã nguồn mở, các ngôn ngữ được biên dịch sẽ dễ dàng ẩn mã hơn nhiều. Nếu bạn từng có kế hoạch cung cấp dự án của mình cho người khác tải xuống và chạy trên máy chủ của riêng họ, thì bạn đang vô tình mời một nhà phê bình hoặc cộng tác viên tiềm năng. Vì khá khó [nhưng không phải là không thể] để ẩn mã nguồn khỏi người dùng có thể tải xuống dự án của bạn, nên có khả năng mọi người bắt đầu xem xét và thay đổi mã của bạn
Nói chung, đó là một điều tốt vì họ có thể đang cải thiện chất lượng và tính hữu ích của dự án và hy vọng họ sẽ đóng góp những cải tiến của mình cho cộng đồng người dùng. Trong trường hợp như vậy, bạn sẽ rất vui vì bạn đã tuân theo một tiêu chuẩn mã hóa và thêm nhận xét trong toàn bộ mã. Nó sẽ làm cho việc hiểu mã của bạn dễ dàng hơn nhiều và bất kỳ ai đọc mã sẽ có ấn tượng rằng bạn thực sự là một người chuyên nghiệp.
Tuyệt vời, bạn nói, làm cách nào để đảm bảo rằng tôi luôn tạo tài liệu hữu ích như vậy khi lập trình? . Bạn cần đầu tư một ít thời gian để học [các] công cụ phù hợp. Đó là phần dễ dàng đối với một người nào đó trong lĩnh vực công nghệ, nơi các bộ kỹ năng đang được mở rộng cứ sau vài năm. Phần khó là áp dụng kiến thức đó một cách nhất quán. Giống như nhiều điều khác trong cuốn sách này, vấn đề là rèn luyện bản thân để có những thói quen tốt. Viết tài liệu cấp API cùng lúc với việc triển khai một lớp hoặc phương thức sẽ trở thành bản chất thứ hai giống như việc tuân theo tiêu chuẩn mã hóa hoặc kiểm tra đúng mã của bạn
May mắn thay, có một số công cụ có thể loại bỏ hầu hết sự tẻ nhạt trong việc ghi lại mã của bạn. Trước hết, các IDE hiện đại [Môi trường phát triển tích hợp] rất tốt trong việc tự động trích xuất một số thông tin cần thiết. Các mẫu có thể giúp bạn tạo các thẻ tài liệu khá nhanh
Mức độ chi tiết
Khi bạn tạo tài liệu của mình, bạn phải quyết định mức độ chi tiết mà bạn muốn nhận. Tôi đã thấy các dự án mà một nửa mã nguồn dễ dàng bao gồm các nhận xét và tài liệu tạo ra tài liệu tuyệt vời dành cho nhà phát triển và người dùng cuối. Tuy nhiên, điều đó có thể không cần thiết hoặc không phù hợp với dự án của bạn. Đề xuất của tôi là tìm ra mức độ nỗ lực hợp lý mà bạn có thể mong đợi ở bản thân liên quan đến những gì sẽ phù hợp với đối tượng mục tiêu của bạn. Rốt cuộc, không chắc là bạn sẽ bắt đầu viết tài liệu cho mọi dòng mã khác nếu bạn không quen với việc thêm bất kỳ tài liệu nào. Một mặt, nếu đối tượng của bạn tương đối nhỏ và phức tạp, bạn có thể thu được ít tài liệu hơn. Mặt khác, nếu bạn đang ghi lại API dịch vụ web cho một dịch vụ trực tuyến lớn khi bạn đang viết mã cho nó, bạn có thể muốn càng chính xác và rõ ràng càng tốt. Thêm nhiều ví dụ và hướng dẫn có thể cho phép ngay cả những nhà phát triển mới bắt đầu sử dụng API của bạn một cách nhanh chóng. Trong trường hợp đó, thành công của chủ lao động của bạn trên thị trường gắn liền trực tiếp với chất lượng và khả năng tiếp cận của tài liệu. Trong trường hợp này, tài liệu là một phần rất quan trọng của sản phẩm chứ không phải là một phần bổ trợ
Ở một đầu của quang phổ, bạn có thể có tài liệu liên quan đến toàn bộ dự án, chẳng hạn như tệp “README”. Ở cấp độ tiếp theo, bạn có thể có phần tài liệu ở đầu mỗi tệp. Bằng cách đó, bạn có thể trình bày chức năng của tệp hoặc lớp mà không đi sâu vào chi tiết
Giới thiệu phpDocumentorphpDocumentor là một dự án Nguồn mở đã tự khẳng định mình là công cụ thống trị để ghi lại mã PHP. Mặc dù có nhiều giải pháp khác, nhưng cho đến nay, phpDocumentor vẫn là giải pháp mà bạn có nhiều khả năng gặp phải nhất trong công việc của mình–và vì lý do chính đáng. Lấy manh mối từ các công cụ tài liệu tương tự ra đời trước nó, chẳng hạn như JavaDoc, phpDocumentor cung cấp nhiều tính năng về giao diện người dùng, định dạng, v.v.
PhpDocumentor cung cấp cho bạn một thư viện lớn các thẻ và đánh dấu khác mà bạn có thể sử dụng để nhúng nhận xét, tài liệu và hướng dẫn vào mã nguồn của mình. Đánh dấu phpDoc được PHP xem dưới dạng nhận xét khi nó thực thi tệp nguồn của bạn và do đó không can thiệp vào chức năng của mã. Tuy nhiên, chạy dòng lệnh phpDocumentor có thể thực thi được hoặc sử dụng giao diện dựa trên web, bạn có thể xử lý tất cả các tệp nguồn của mình, trích xuất nội dung liên quan đến phpDoc và biên dịch nó thành tài liệu chức năng. Không cần xem qua các tệp nguồn vì phpDocumentor tập hợp tài liệu thành các trang HTML, tệp văn bản, PDF hoặc CHM trông đẹp mắt
Mặc dù phpDocumentor hỗ trợ lập trình thủ tục và PHP4, trọng tâm của bài viết này sẽ là sử dụng nó để ghi lại các ứng dụng được phát triển với thiết kế hướng đối tượng. Cụ thể, chúng ta sẽ xem xét cách lập tài liệu chính xác về giao diện, lớp, thuộc tính và phương thức. Để biết chi tiết về cách ghi lại một số phần tử PHP4 thường không xuất hiện trong quá trình triển khai hướng đối tượng của PHP5, vui lòng tham khảo hướng dẫn trực tuyến của phpDocumentor. http. //thủ công. phpdoc. tổ chức/
Cài đặt phpDocumentor
Có hai cách cài đặt phpDocumentor. Cách ưa thích là sử dụng kho lưu trữ PEAR. Nhập lê cài đặt PhpDocumentor từ dòng lệnh sẽ đảm nhiệm việc tải xuống, giải nén và cài đặt phpDocumentor cho bạn. Tiện ích quả lê thường được bao gồm trong bất kỳ bản phân phối chuẩn nào gần đây của PHP. Tuy nhiên, nếu vì lý do nào đó bạn cần cài đặt nó trước, bạn có thể tải xuống từ trang PEAR. http. //Lê. php. net/
Trước khi chúng tôi tiến hành cài đặt, có một cài đặt quan trọng cần xem xét. Theo truyền thống, phpDocumentor đã được chạy từ dòng lệnh, tuy nhiên, các phiên bản gần đây hơn đi kèm với giao diện dựa trên web khá chức năng. Nếu bạn muốn lê cài đặt giao diện người dùng web vào thư mục con của thư mục gốc tài liệu của máy chủ web của bạn, trước tiên bạn sẽ phải đặt biến data_dir của lê thành đường dẫn tuyệt đối đến thư mục đó. Trong trường hợp của tôi, tôi đã tạo một trang cục bộ từ đó tôi có thể truy cập các ứng dụng khác nhau do lê cài đặt. Thư mục đó là /Users/dirk/Sites/phpdoc. Từ thiết bị đầu cuối, bạn sẽ thấy thông tin sau nếu bạn cho lê biết nơi cài đặt phần web và tiến hành cài đặt phpDocumentor
[email protected]
* @link //www.waferthin.com Check out my site
*/
class Translate
{
}
Ngoài các thẻ "tiêu chuẩn" ở trên, phpDocumentor nhận ra các thẻ "nội tuyến", tuân thủ cùng một cú pháp, với sự khác biệt đáng chú ý duy nhất là chúng được đặt trong dấu ngoặc nhọn. Thẻ nội tuyến xuất hiện nội tuyến với các mô tả ngắn và dài như thế này
/**
* There is not enough space here to explain the value and usefulness
* of this class, but luckily there is an extensive tutorial available
* for you: {@tutorial ForeignLanguageParser/Tran slate.cls}
*/
Mẫu DocBlock
Thường xảy ra trường hợp các thẻ giống nhau áp dụng cho nhiều phần tử liên tiếp. Ví dụ: bạn có thể nhóm tất cả các khai báo thuộc tính riêng ở đầu lớp. Trong trường hợp đó, sẽ khá lặp đi lặp lại khi liệt kê lặp đi lặp lại các DocBlock giống nhau hoặc gần giống nhau. May mắn thay, chúng ta có thể tận dụng các mẫu DocBlock, cho phép chúng ta xác định các phần DocBlock sẽ được thêm vào DocBlock của bất kỳ phần tử nào giữa điểm bắt đầu và điểm kết thúc được chỉ định
Các mẫu DocBlock trông giống như các DocBlock thông thường với sự khác biệt là dòng đầu tiên bao gồm /**#@+ thay vì /**. Các thẻ trong mẫu sẽ được thêm vào tất cả các DocBlocks tiếp theo cho đến khi phpDocuenter gặp chuỗi ký tự kết thúc /**#@-*/
Hai đoạn mã sau sẽ tạo ra cùng một tài liệu. Đầu tiên, đây là phiên bản chỉ chứa DocBlocks tiêu chuẩn
Và đây là đoạn sẽ tạo ra cùng một tài liệu bằng cách sử dụng ký hiệu ngắn gọn hơn bằng cách tận dụng các mẫu DocBlock
Chia sẻ
liên kết
gói
ĐỂ LẠI TRẢ LỜI
Vui lòng nhập nhận xét của bạn
Vui lòng nhập tên của bạn vào đây
Bạn đã nhập sai địa chỉ email
Vui lòng nhập địa chỉ email của bạn vào đây
Lưu tên, email và trang web của tôi trong trình duyệt này cho lần bình luận tiếp theo
Δ
Phải đọc trong lập trình
Học các lệnh Linux cần thiết để điều hướng Shell một cách hiệu quả
Mạng lưới chuyên gia - Ngày 16 tháng 8 năm 2021 - 3. 45 giờ sáng
Khi chúng ta tìm hiểu cách triển khai máy chủ Ubuntu, cách quản lý người dùng và cách quản lý các gói phần mềm, chúng ta nên dành một chút thời gian