Mã tài liệu đầu tiên? [đóng cửa]

Có ai đã từng thử tạo một tài liệu mã hoàn chỉnh trước, trước khi thực sự viết mã chưa? Tôi đã suy nghĩ về điều này sớm hơn bởi vì tôi nghĩ rằng nó sẽ giúp viết một giao diện cụ thể và sẽ đảm bảo thiết kế ban đầu của bạn không bị trôi nổi bằng cách khiến bạn nghĩ về cách các lớp tương tác. Đây có phải là một ý tưởng tốt? Có ai đã thử nó chưa? Ell

Đúng.

Nó khiến bạn suy nghĩ về những gì, chính xác, mã của bạn phải làm gì. Ý tưởng là bạn có thể bắt đầu với bất kỳ phần nào của mã và biết chính xác những gì cần phải làm để hoàn thành mô-đun đó.

Nó cũng dễ dàng sửa một cái gì đó trên bảng vẽ hơn trong IDE.

Có hai cách nghĩ về nó:

1) Tài liệu như trong tài liệu Word, Wiki, v.v. Theo định nghĩa, bạn không thể có một tài liệu mã hoàn chỉnh vì bạn không có mã để làm tài liệu. Bạn có thể thử ghi lại thiết kế cấp cao, các giả định, giao diện và hợp đồng trước.

2) Tài liệu như các bài kiểm tra thực thi. Có một trường phái cho rằng các bài kiểm tra đơn vị thực thi là tài liệu tốt nhất. Trường phái tư tưởng này cũng ủng hộ loại tài liệu này trước khi viết mã (TDD). Đồng thời, bạn không viết tất cả các bài kiểm tra cho toàn bộ hệ thống ngay từ đầu. Bạn phân tích nó bằng các trường hợp sử dụng trước, sau đó bạn thực hiện kiểm tra và mã cho mỗi trường hợp sử dụng.

Bắt đầu với tài liệu là mô hình thác nước cổ điển và có tất cả những cạm bẫy liên quan đến mô hình đó. Nhìn rộng ra, bạn càng có nhiều tài liệu thì bạn càng phải cập nhật khi các yêu cầu thay đổi. Một lợi ích của việc bắt đầu với tài liệu người dùng là bạn có thể nhận được phản hồi (và do đó thay đổi) sớm hơn. Nhưng kinh nghiệm cho thấy hầu hết mọi người đều tệ trong việc lập bản đồ tài liệu về hành động. Vì vậy, chúng tôi sử dụng các nguyên mẫu thay thế, cho phép mọi người thực sự sử dụng phần mềm và đưa ra phản hồi theo cách đó.

Một biến thể của "tài liệu đầu tiên" là lập trình biết chữ . Bắt đầu bằng cách viết một mô tả về những gì chương trình sẽ làm từ góc độ lập trình viên. Tiếp tục điều chỉnh cho đến khi nó biên dịch. Voila, một chương trình biết chữ.

Cá nhân tôi thấy tốt hơn khi sử dụng các sơ đồ (như UML) để thực hiện mô hình đơn giản để hiển thị dòng chảy của mọi thứ. Điều này nhanh hơn nhiều so với việc ghi lại những điều bằng lời và nếu được thực hiện đúng có thể chỉ là mô tả. Mặc dù vậy, tôi sẽ do dự khi làm Tài liệu đầy đủ vì cá nhân tôi chưa từng có một dự án nào mà tôi đã làm mà không thay đổi trong quá trình lập trình.

EDIT: Một số tài liệu mặc dù nên được thực hiện khi bạn đi lâu. Điều này làm cho nó dễ dàng hơn để làm tài liệu đầy đủ sau này.

Joshua Bloch thảo luận về điểm này trong cuộc phỏng vấn của mình cho cuốn sách "Coders at Work".

Trái với quan điểm chính thống và hàn lâm hơn, ông khuyên bạn điều gì đó để điều chỉnh suy nghĩ của bạn (có thể bạn đã tự đọc nó ở đó?): Rằng trước khi viết tài liệu bạn phải hiểu những gì bạn muốn từ hệ thống và có được "thực tế hơn" " cảm giác. Với mục đích này, anh ta sẽ thiết kế một phần của các giao diện và một số mã máy khách sử dụng chúng.

Điều quan trọng nhất là phải biết những gì bạn đang cố gắng xây dựng: vấn đề nào bạn đang cố gắng giải quyết. Tầm quan trọng của phân tích yêu cầu không thể được phóng đại. Có những người nghĩ rằng, Oh Oh, yeah, yêu cầu phân tích; bạn đến khách hàng của bạn, bạn nói, 'Bạn cần gì?' Anh ấy nói với bạn, và bạn đã hoàn thành.

Không gì có thể hơn được sự thật. Không chỉ là một cuộc đàm phán mà nó còn là một quá trình hiểu biết. Nhiều khách hàng sẽ không cho bạn biết một vấn đề; họ sẽ cho bạn biết một giải pháp. Chẳng hạn, một khách hàng có thể nói, tôi cần bạn thêm hỗ trợ cho 17 thuộc tính sau vào hệ thống này. Sau đó, bạn phải hỏi, 'Tại sao? Bạn sẽ làm gì với hệ thống? Làm thế nào để bạn mong đợi nó sẽ phát triển? 'Vv và như vậy. Bạn qua lại cho đến khi bạn tìm ra tất cả những gì khách hàng thực sự cần phần mềm để làm. Đây là những trường hợp sử dụng.

Đến với một bộ trường hợp sử dụng tốt là điều quan trọng nhất bạn có thể làm trong giai đoạn này. Một khi bạn có điều đó, bạn có một điểm chuẩn để bạn có thể đo bất kỳ giải pháp nào có thể. Sẽ ổn thôi nếu bạn dành nhiều thời gian để đưa nó gần đúng, bởi vì nếu bạn hiểu sai, bạn đã chết. Phần còn lại của quá trình sẽ là một bài tập vô ích.

Điều tồi tệ nhất mà bạn có thể làm được và tôi đã thấy điều này xảy ra, đó là bạn đưa một nhóm người thông minh vào phòng làm việc trong sáu tháng và viết một đặc tả hệ thống gồm 247 trang trước khi họ thực sự hiểu họ là ai cố gắng xây dựng. Bởi vì sau sáu tháng, họ sẽ có một hệ thống được chỉ định rất chính xác có thể là vô dụng. Và họ thường nói, chúng tôi đã đầu tư rất nhiều vào thông số kỹ thuật mà chúng tôi phải xây dựng nó. Vì vậy, họ xây dựng hệ thống vô dụng và nó không bao giờ được sử dụng. Và điều đó thật kinh khủng. Nếu bạn không sử dụng các trường hợp sử dụng, bạn xây dựng mọi thứ và sau đó bạn cố gắng làm một việc rất đơn giản và bạn nhận ra rằng, Ôi trời ơi, làm một việc rất đơn giản như lấy một tài liệu XML và in nó yêu cầu các trang trên các trang của bản tóm tắt mã. Và đó là một điều khủng khiếp.

- Joshua Bloch, từ một cuộc phỏng vấn trong " Coders tại nơi làm việc: Những phản ánh về nghề lập trình " của Peter Seibel

Nếu bạn đã suy nghĩ theo những dòng này, sẽ tốt hơn nếu bạn có thể cầm cuốn sách và đọc toàn bộ cuộc phỏng vấn. Như tôi đã nói, anh ấy luôn rất giác ngộ.

Một số người thậm chí còn đi xa hơn và nói rằng một công ty nên hoàn toàn làm việc ngược lại, vì vậy

1. Viết thông cáo báo chí
2. Viết một câu hỏi thường gặp
3. Xác định trải nghiệm của khách hàng
4. Viết hướng dẫn sử dụng
5. Bắt đầu lập trình

Xem http://www.allthingsdistribution.com/2006/11/usiness_backwards.html

Viết tài liệu mã hoàn chỉnh trước tiên có lẽ là quá mức cần thiết và phần nào gợi nhớ đến phương pháp thác nước. Tuy nhiên, tôi đã thấy rằng một cách tiếp cận thực tế hơn là viết README trước. Đây là lý do tại sao:

README không ghi lại mọi chi tiết của dự án của bạn. Thay vào đó, nó thường chứa thông tin sau:

1. Mô tả : "khoảng cách bán hàng" ngắn. Nói với người đọc tại sao họ nên tiếp tục đọc.
2. Ví dụ nhanh : đoạn mã ngắn hoặc ảnh chụp màn hình để hỗ trợ mô tả.
3. Bắt đầu nhanh : cách đi, cài đặt hướng dẫn và nhiều ví dụ khác.
4. Tài liệu khác : liên kết đến các tài liệu đầy đủ và thêm thông tin.
5. Tổ chức dự án : ai là tác giả, cách đóng góp, cách nộp lỗi.
6. Thông báo pháp lý : giấy phép, bản quyền và bất kỳ chi tiết pháp lý nào khác.

Viết "mục đích bán hàng" lên phía trước buộc tôi phải rõ ràng về lý do tại sao dự án này nên tồn tại và tại sao các nhà phát triển nên sử dụng nó. Hành động đơn thuần là viết các câu đầy đủ để mô tả dự án thường thay đổi nó tốt hơn: bạn hiểu nó tốt hơn, phát triển ý tưởng mới và phát hiện ra các vấn đề tiềm ẩn. Đây cũng là một công cụ ưu tiên tuyệt vời: bất cứ điều gì trong "mục đích bán hàng" là phải có!

"Ví dụ nhanh" và "hướng dẫn bắt đầu nhanh" buộc tôi phải suy nghĩ thông qua các trường hợp sử dụng chính theo quan điểm của người dùng. Tôi đã thấy rằng làm điều này trước khi viết bất kỳ mã nào - trước khi bị sa lầy vào các chi tiết triển khai và thời hạn chặt chẽ - dẫn đến các API và thiết kế sạch hơn nhiều. Hãy nhớ rằng: các chương trình nên được viết cho mọi người đọc và chỉ tình cờ cho các máy thực thi ( SICP ).

Trong "tài liệu tiếp theo", tôi tạo ra một phác thảo về các phần sẽ cần tài liệu chi tiết, sẽ được thực hiện sau. "Tổ chức dự án" cho phép tôi tìm ra ai sẽ làm việc trong dự án và thực tiễn mã hóa. "Thông báo pháp lý" ... tốt, cũng có thể giúp họ tránh xa.

Khi bạn đã có README cơ bản này, bạn có một tài liệu hữu ích để thảo luận, đánh giá thiết kế, phân chia công việc và lập kế hoạch dự án. Khi bạn làm việc trong dự án, thường xuyên kiểm tra lại với README để đảm bảo bạn vẫn đang đi đúng hướng. Ngoài ra, tăng dần cập nhật README và "tài liệu thêm" khi bạn đi có nghĩa là tất cả tài liệu của bạn sẽ được thực hiện khi mã được thực hiện, đó là một trải nghiệm thú vị hơn nhiều so với việc phải vội vàng ghi lại mọi thứ vào phút cuối.

Để biết thêm thông tin, hãy kiểm tra như sau:

1. Phát triển theo hướng Readme
2. Mã quan trọng nhất không phải là mã
3. Bạn là những gì bạn tài liệu

Tại sao bạn không muốn nghĩ về cách các lớp tương tác? Tại sao đó là một điều xấu? Tôi thực sự nghĩ về các tương tác trước khi tôi biết các lớp là gì. Bằng cách đó, các lớp tự xác định.

Bạn nên có một số ý tưởng về những gì bạn dự định làm trước khi bạn viết mã. Vấn đề luôn là làm thế nào để bạn giữ những gì bạn đã mã hóa đồng bộ với những gì bạn đã viết? Một số người nói đừng thử, những người khác nói hãy quên các tài liệu ban đầu và tiếp tục bình luận. Tất nhiên mã luôn là nguồn chính tắc. Vấn đề sau đó trở thành liệu có đáng nỗ lực để ghi lại những gì mã làm cho những người đến sau hoặc sử dụng mã. Bất cứ ai cũng có thể tìm ra những gì một chức năng làm. Công việc của người viết là giúp ai đó hiểu trong 5 phút những gì mọi người có thể tìm ra trong một giờ. Thêm deltas và xác định đường dẫn của bạn.