Bạn có nghĩ rằng mã là tài liệu tự? [đóng cửa]

Đây là một câu hỏi đã được đặt ra cho tôi từ nhiều năm trước khi là một người cấp bậc trong một cuộc phỏng vấn xin việc và nó bị cằn nhằn trong não tôi bây giờ và tôi chưa bao giờ thực sự tìm thấy một câu trả lời tốt làm tôi hài lòng.

Người phỏng vấn trong câu hỏi đang tìm kiếm một câu trả lời trắng đen, không có trung gian. Tôi chưa bao giờ có cơ hội để hỏi về lý do đằng sau câu hỏi, nhưng tôi tò mò tại sao câu hỏi đó sẽ được đặt cho nhà phát triển và bạn sẽ học được gì từ câu trả lời có hay không?

Theo quan điểm của riêng tôi, tôi có thể đọc Java, Python, Delphi, v.v., nhưng nếu người quản lý của tôi đến gặp tôi và hỏi tôi bao lâu trong một dự án và tôi nói "Mã đã hoàn thành 80%" (và trước đó bạn bắt đầu bắn hạ tôi, tôi đã nghe thấy điều này được nói ra trong một vài văn phòng của các nhà phát triển), chính xác thì đó là tài liệu như thế nào? Xin lỗi nếu câu hỏi này có vẻ lạ, nhưng tôi muốn hỏi và có một số ý kiến ​​về nó để hiểu rõ hơn về lý do tại sao nó sẽ được đưa cho một người nào đó trong một cuộc phỏng vấn.

Một phần.

Mã sử ​​dụng các từ tiếng Anh lớn có thể tự ghi lại một phần trong đó các tên cho tất cả các hàm và biến có thể cho bạn biết nó đang làm gì. Nhưng nó có thể sẽ không cho bạn biết lý do tại sao.

Đối chiếu:

a->b;
# what is b doing? what is the a object?

carEngine->startIgnition;
# much more clear what objects are involved

Nhưng bạn vẫn không biết tại sao một chiếc xe đang được khởi động. Do đó, chỉ một phần. Thật là khủng khiếp khi người phỏng vấn của bạn đang mong đợi một câu trả lời trắng đen, trừ khi quan điểm của anh ấy về màu đen và trắng có thể rất mạnh mẽ.

Mã số tự nó không phải là tài liệu tự.

Lý do là mã nêu rõ CÁCH và không quan tâm TẠI SAO đó là những gì con người cần biết để duy trì mã.

Do đó, bạn cần thêm ý kiến ​​giải thích tất cả lý do TẠI SAO . Bạn có thể giới hạn chúng bằng cách để tên biến của bạn bao gồm một phần của các quyết định, nhưng bạn không thể tránh chúng.

Mã thích hợp cho bạn biết " làm thế nào ". Nhận xét đúng cho bạn biết " tại sao " .

Do đó, mã có thể tự ghi lại theo cách mà mọi thứ đạt được, nhưng bạn không thể cho rằng nó ghi lại lý do tại sao.

Nếu họ khăng khăng một câu trả lời trắng đen mà không cho phép trung dung, câu trả lời là không.

Câu trả lời đầy đủ hơn là mã phải tự ghi lại tài liệu ở mức tối đa hợp lý, nhưng không có cách nào hợp lý để đưa một số loại tài liệu vào mã. Ví dụ, mã có thể làm tốt việc ghi lại thông tin nào được thu thập trên mẫu A, mẫu B và mẫu C. Thông thường, nó sẽ không (và có lẽ không nên) cố gắng ghi lại các thử nghiệm cho thấy sự phân chia đó dữ liệu theo cách đó đã giảm các lỗi x% so với (ví dụ) chỉ sử dụng hai biểu mẫu thay vì ba.

Bất cứ điều gì ngoại trừ đoạn mã tầm thường nhất đều có thể được hưởng lợi từ ít nhất một số tài liệu bên ngoài.

Câu trả lời của tôi. Trong phạm vi lớn nhất có thể, bạn nên cố gắng làm cho mã của bạn tự ghi lại tài liệu càng tốt. Có nhiều lý do cho việc này. Khi ban đầu được viết, trung bình một dòng trong 10 có lỗi. Những sai lầm trong mã có xu hướng được tìm thấy và sửa chữa. Những sai lầm trong tài liệu có xu hướng bị bỏ lại. Và trong bảo trì, thông thường mã và tài liệu bị trôi đi.

Điều đó nói rằng, có những hạn chế đối với những gì có thể được thực hiện bằng cách làm cho mã rõ ràng. Trong những trường hợp đó, bạn phải ghi lại.

Còn trường hợp bạn có sự lựa chọn về tài liệu thì sao? Quan điểm của tôi là bảo trì phụ thuộc mạnh mẽ vào tổ chức của bạn. Nếu bạn có các nhà phát triển phần mềm xuất sắc và quy trình xem xét mã nghiêm ngặt (ví dụ như Google làm), thì quy trình của bạn và mọi người có thể khiến bạn không cần phải lo lắng về các bình luận không được duy trì. Trong trường hợp đó, một phong cách bình luận nặng nề hơn rất nhiều ý nghĩa. (Trên thực tế, Google có phong cách nặng về nhận xét.) Tuy nhiên, nếu bạn có một tổ chức tiêu biểu hơn thì tôi sẽ không tin tưởng bất kỳ bình luận nào tôi thấy, và tôi sẽ hy vọng rằng bạn có những người tin rằng trong việc cố gắng làm cho mã tự viết tài liệu. Trong tình huống đó tôi sẽ coi ý kiến ​​là thừa.

Để có một cuộc trò chuyện thú vị về những ưu điểm và nhược điểm của việc bình luận, hãy xem http://www.perlmonks.org/index.pl?node_id=65153 cho một cuộc trò chuyện cũ mà tôi là một phần của. (Lưu ý, cùng lúc chúng tôi có cuộc trò chuyện đó, có một cuộc trò chuyện riêng tư thân thiện hơn. Tôi luôn hối hận vì chỉ có một nửa cuộc trò chuyện tiêu cực hơn là công khai.) Ý kiến ​​của tôi không còn phù hợp với những gì tôi nghĩ lúc đó , nhưng tôi vẫn nghĩ rằng cuộc trò chuyện có thức ăn đáng giá để suy nghĩ.

Tôi thấy rằng câu hỏi này xuất hiện rất nhiều, và thường có một sự tôn sùng tôn giáo về nó. Tôi đã bắt nó ở đây...

Trong một thế giới lý tưởng, tuyên bố sau đây có thể được đưa ra:

Mã phải được viết theo cách như vậy, rằng logic có thể được theo sau mà không cần bình luận.

OK, điều này là đủ công bằng, nhưng vấn đề là chúng ta không sống trong một thế giới lý tưởng. Có một số vấn đề với việc đạt được tuyên bố lý tưởng này.

1. Các lập trình viên thường không phải là chuyên gia trong ngành mà họ đang lập trình chống lại. Thật dễ dàng để hiểu một chức năng như startEngine(Car car)(hầu hết) mọi người đều có thể hiểu những gì đang được hỏi ở đây. Nhưng di chuyển đến thế giới thực, và mọi thứ trở nên mờ nhạt hơn. Ví dụ, chức năng getSess(String tid, String aid)này hoàn toàn dễ hiểu đối với một kỹ sư vận tải, người hiểu các hệ thống DWDM, nhưng nó có thể đưa ra một thách thức cho lập trình viên mới vừa đưa vào dự án. Nhận xét được đặt tốt có thể giúp dễ dàng chuyển đổi để hiểu mã một cách kịp thời.

2. Các lập trình viên được yêu cầu duy trì mã thường không có kỹ năng như các kiến ​​trúc sư ban đầu của mã. Lập trình viên ban đầu có thể đã có đủ kỹ năng để viết một thuật toán nhanh, ngắn gọn, hiệu quả để hoàn thành một nhiệm vụ cụ thể. Nhưng lập trình viên được giao nhiệm vụ duy trì mã đó có thể đấu tranh với việc cố gắng hiểu những gì đang xảy ra. Nhận xét được đặt tốt có thể giúp dễ dàng chuyển đổi để hiểu mã một cách kịp thời.

3. Đã bao nhiêu lần bạn viết một chút mã, mà sau đó bạn phải vật lộn để hiểu tại sao bạn làm điều đó, hoặc thậm chí những gì bạn đang cố gắng để đạt được? Tất cả chúng ta làm điều đó theo thời gian. Giải quyết một vấn đề và tạo ra một giải pháp dễ theo dõi cho một vấn đề thường là hai tư duy khác nhau. Trừ khi bạn là người có thể viết mã hoàn hảo ra khỏi cổng, bạn thường làm rất nhiều lỗi với mã của bạn khi bạn đi cùng. Bạn cũng có thể không thể quay lại đoạn mã này một lúc. Nhận xét được đặt tốt có thể giúp dễ dàng chuyển đổi để hiểu mã một cách kịp thời.

4. Tình huống độc đáo đòi hỏi phải giải thích. Ví dụ, một lập trình viên có thể tự hỏi tại sao tạm dừng 100ms được đưa vào một chút mã giao tiếp với thiết bị DWDM. Để các lập trình viên tiếp theo biết rằng cần phải tạm dừng vì thiết bị chậm hấp thu và có thể bỏ lỡ lệnh sẽ là một thông tin quý giá cần có. Nhận xét được đặt tốt có thể giúp dễ dàng chuyển đổi để hiểu mã một cách kịp thời.

Viết một cách độc đáo, mã "tự ghi" là một niềm vui để tìm thấy. Mã được viết độc đáo, "tự viết tài liệu", với các bình luận được đặt tốt, có nhiều thông tin là một ơn trời và là một phát hiện rất hiếm.

Chỉ cần đưa ra lập luận ở mỗi bên của câu hỏi ban đầu:

Có, mã là tài liệu tự. Các biến, phương thức và tên lớp đều có thể được thực hiện để dễ đọc và dễ hiểu vì vậy đây là một hình thức tự viết tài liệu. Có thể có một cái gì đó trong kiểu mã cung cấp tài liệu XML ở cuối được coi là thủ tục tiêu chuẩn. Nói cách khác, đây là một phần công việc của nhà phát triển để cung cấp tài liệu có thể được trộn lẫn với mã.

Không, mã không phải là tài liệu tự. Các quyết định kinh doanh được đưa ra, các lựa chọn thiết kế được đưa ra và các yếu tố khác sẽ không xuất hiện trong các dòng mã và nên được viết ra bên ngoài cơ sở mã. Do đó, tài liệu bên ngoài là cần thiết và đây là những ví dụ về nó.

Điểm hỏi: Bạn sẽ đưa ra một câu trả lời một phần nhận ra những hạn chế của câu trả lời hoặc bạn sẽ mù quáng dựa vào bất kỳ khía cạnh nào bạn tin là thực tiễn tốt hơn? Bạn có bao nhiêu niềm tin trong câu trả lời của mình nếu nó là có hay không? Nó có thể được coi là một câu hỏi căng thẳng được thiết kế để thoát ra khỏi một người có thể trả lời, "Cái gì ...? Đó là câu hỏi ngớ ngẩn nhất mà bạn có thể hỏi tôi. Tôi từ chối trả lời với lý do nó xúc phạm trí thông minh của tôi vượt quá niềm tin! " như một câu trả lời khá kiêu ngạo và khoa trương mà tôi có thể hình dung một số người đưa ra câu trả lời với giọng điệu đó.

Rõ ràng anh ta là một lập trình viên biết chữ theo phong cách của Knuth. Đối với môn đệ LP, mã phải tự ghi lại để hợp lệ. Vì vậy, câu trả lời duy nhất có thể là "có".

Vấn đề ở đây là không có nhiều ngôn ngữ lập trình biết chữ và không có ngôn ngữ nào tôi biết về việc sử dụng thương mại rộng rãi. Vì vậy, nó sẽ phải là một vị trí thích hợp ở đâu đó.

Tôi nghĩ rằng những gì người phỏng vấn có thể đã tìm kiếm là: "Làm thế nào để bạn tự viết mã tài liệu?" với ngụ ý "thái độ của bạn đối với tài liệu là gì?"

Tôi đã đi đến một bài giảng thực sự truyền cảm hứng bởi một anh chàng tên Robert C Martin khi anh ấy nói về chương 'phương pháp viết' của cuốn sách Clean Code.

Rõ ràng anh ta đã trình bày một chút về vị trí của một người theo chủ nghĩa thuần túy, nhưng tôi đã đưa ra lời khuyên của anh ta rằng khi bạn cắt mã của mình thành các phương pháp có thể tái sử dụng nhỏ và sử dụng các thủ thuật đơn giản như:

• Giữ tất cả các câu lệnh trong một phương thức ở cùng một mức độ trừu tượng
• Kéo các nội dung của điều kiện luồng điều khiển hoặc các khối vòng lặp vào các cuộc gọi phương thức
• Khi bạn thấy mình truyền cùng một tham số vào một số phương thức trong một lớp, hãy tách ra một lớp mới
• Và các thủ thuật đơn giản như thay thế các biểu thức boolean khó hiểu bằng các cuộc gọi phương thức
• v.v ...

Bạn kết thúc với mã tài liệu có thể đọc được, hơi tự đọc (miễn là bạn nỗ lực vào các tên ngắn gọn nhưng mô tả) dễ hiểu và dễ duy trì hơn.

Tôi đã thấy rằng những thứ đó thực sự hữu ích, nhưng nó đòi hỏi kiến ​​thức về các mẫu thiết kế để làm tốt và bạn chắc chắn cần phải bổ sung cách tiếp cận với tài liệu phương pháp lớp và cấp cao.

Thông thường mã tự viết tài liệu đề cập đến việc sử dụng quy ước đặt tên cho các biến, hàm, v.v ... sao cho mục đích của mã là hiển nhiên. Vì vậy, không có mã tự nó không phải là tài liệu tự. Tôi không hiểu những gì bạn đang đề cập đến trong đoạn thứ ba. Điều đó dường như không có gì để làm với mã tài liệu tự.

Jack Reeves đã đưa ra một lập luận thuyết phục rằng mã là thiết kế . Theo như nhiều người quan tâm thì mã thực tế là "tài liệu" duy nhất cho bạn biết hệ thống làm gì. Mọi thứ khác phân rã khi một hệ thống sống có xu hướng trôi xa hơn và xa hơn khỏi hệ thống được thiết kế. Ngay cả khi bạn đã tạo một tài liệu từ mã (giống như nhiều công cụ UML có thể làm hiện nay), thì đó vẫn chỉ là một tài liệu chính xác của hệ thống tại thời điểm đó .

Vì vậy, có mã là tài liệu tự. Làm thế nào tốt nó được ghi lại là một câu hỏi khác hoàn toàn.

Khi tôi trở nên có kinh nghiệm hơn, tôi đã học được rằng câu trả lời thực sự là mã cộng với môi trường của người đọc quyết định mức độ tự viết tài liệu.

Để giảm thiểu phương sai giữa môi trường của người đọc và môi trường của người viết, chúng tôi thêm nhận xét. Càng nhiều bình luận cần thiết, điển hình là người viết ít kinh nghiệm. Có một bài luận khá tuyệt vời ngoài kia mô tả khía cạnh phát triển phần mềm này, nhưng tôi không nhớ ai đã viết nó hoặc nơi tôi tìm thấy nó.

Tôi biết câu trả lời mà hầu hết mọi người mong đợi cho câu hỏi đó là "không", nhưng tôi sẽ nói có. Nếu tôi được hỏi điều này trong một cuộc phỏng vấn cho một công việc, tôi vẫn sẽ nói có.

Tôi đã làm việc trên nhiều dự án khác nhau với nguồn mở và đóng. Họ đã chuyển trong tài liệu từ các nhận xét đơn giản để lại dưới dạng ghi chú của lập trình viên đến tài liệu API đầy đủ. Mặc dù tài liệu API có thể rất tuyệt, cuối cùng tôi đã luôn gặp phải tình huống trong đó tài liệu bằng ngôn ngữ viết không đủ để xác định hành vi thực tế của mã. Cuối cùng tôi đã xem xét mã nguồn, thiết kế ngược các ứng dụng hoặc làm phiền các nhà phát triển có quyền truy cập nguồn để xem mã nguồn và chỉ định thêm.

Đối với tôi, mã là tài liệu cuối cùng. Cho dù bạn viết bao nhiêu từ mà chương trình sẽ làm, hành vi chính xác được xác định bởi mã.

Tôi đồng ý rằng khi viết mã, bạn nên cố gắng làm cho mã của mình tự mô tả càng tốt. Tuy nhiên, như những người khác đã đề cập, gần như không thể trong một chương trình phức tạp để mô tả hoàn toàn mọi thứ mà mã đang làm. Tôi không phản đối ý kiến, thực tế tôi thấy rằng với những bình luận tốt, việc đọc mã có thể dễ dàng hơn, mặc dù mã có thể tự giải thích mà không cần bình luận đọc tiếng Anh hoặc một số ngôn ngữ nói hầu như luôn luôn dễ dàng hơn.

Tôi thấy rằng tài liệu hữu ích nhất hầu như không bao giờ bình luận. Hầu hết các dự án tôi đang làm gần đây đều có wiki bao gồm tất cả các phần khác nhau, cách chúng kết nối. Tôi cố gắng giải thích những gì trong tâm trí của tôi khi tôi viết mã để những người khác sẽ không phá vỡ mã của tôi vì họ không hiểu lý do tại sao. Nó cũng có thể giúp người khác tái cấu trúc mã với sự tự tin hơn. Tôi thường thấy mình do dự khi cấu trúc lại mã bởi vì tôi không bao giờ biết những gì nó có thể phá vỡ và không có lời giải thích. Ngay cả khi bạn là người duy nhất làm việc trong một dự án tôi đảm bảo trong một hoặc hai năm, bạn sẽ quên tại sao bạn làm điều gì đó ngay cả khi đó là đoạn mã đẹp nhất, bạn vẫn có thể quên tại sao nó lại ở đó.

Chắc chắn, nếu bạn có thời gian không giới hạn. Tôi đã dành hơn 25 năm tài liệu mã cho các nhà phát triển khác. Vị trí của tôi luôn là tôi cố gắng giải thích điều gì đó để một nhà phát triển khác có thể mò mẫm nó trong 5 phút, khi họ có thể chỉ cần kiểm tra mã và tìm ra nó trong nửa giờ. Nếu tôi lưu tất cả những người nhìn vào phương pháp đó 25 phút, thì tôi đã hoàn thành công việc của mình.

Tôi nghĩ rằng sơ đồ lớp phải luôn được sử dụng để ghi lại mã. Tôi không nghĩ rằng nếu bạn nhìn vào mã trực tiếp, bạn có thể thấy kiến ​​trúc hoàn chỉnh. Tôi đồng ý rằng nếu bạn đã tự viết mã hoặc làm việc với nó trong một thời gian dài thì bạn có thể hiểu nhưng mỗi khi có nhu cầu mới xuất hiện mỗi lần bạn cần xem mã và tìm kiếm nơi để thêm mã mới này.

Những gì chúng tôi làm trong công ty của chúng tôi là có sơ đồ lớp về dự án của chúng tôi. Chúng tôi không thực sự dành thời gian mô hình hóa mà chỉ sử dụng sơ đồ lớp để trực quan hóa mã sau khi kỹ thuật đảo ngược. Nếu mã thay đổi thì có một cơ chế hợp nhất và sơ đồ lớp của tôi luôn được cập nhật.

Điều tuyệt vời là có thể thêm ý kiến, các ràng buộc vào sơ đồ bên cạnh tài liệu java. Chúng tôi đảo ngược dự án, sau đó tạo một mô hình và các khung nhìn trích xuất cuối cùng từ mô hình được hiển thị dưới dạng sơ đồ lớp UML. Tôi không viết mã ở giai đoạn này nhưng lấy một bản in màu xanh từ kiến ​​trúc mã và làm việc với nó để tạo hoặc mở rộng kiến ​​trúc hiện tại của tôi. Nếu tôi thích nó thì tôi nhấn một nút và mã hiện tại của tôi được hợp nhất với sơ đồ của tôi. Tôi có nghĩa là hợp nhất và chắc chắn không tạo mã đầy đủ. Chỉ có delta giữa mã hiện tại và sơ đồ của tôi được viết, không phải mã đầy đủ mỗi lần.

Tôi đã bị mắc kẹt trong nhiều năm, có bằng thạc sĩ và vẫn viết mã nhưng tôi không muốn chỉ là một nhà văn java và muốn sử dụng bộ não của mình nhiều hơn một chút. Các khung nhìn UML cung cấp cho tôi những gì tôi cần để suy nghĩ về kiến ​​trúc của mình, giao tiếp với các thành viên khác trong nhóm và tạo kiến ​​trúc tốt hơn mà không cần sử dụng phát triển Model Driven mà chỉ sử dụng đồng bằng giữa mã được viết thủ công và tạo sơ đồ lớp. Tôi tạo kiến ​​trúc của mình ở cấp mã, sau đó đảo ngược nó và nhìn vào mô hình. Tôi tạo các khung nhìn và cố gắng cải thiện kiến ​​trúc của mình trực tiếp trong mã, sau đó đảo ngược lại và xem những gì đã được thực hiện, v.v ... Đó là một phép lặp vĩnh viễn không tạo mã theo mô hình nhưng đồng bộ hóa trực tiếp hoặc hợp nhất giữa mã và UML. Điều tôi thích là mã điều khiển UML và chắc chắn không ngược lại.