Sếp của tôi muốn một lời giải thích bằng tiếng Anh từng dòng về mã của chúng tôi

Tôi đặc biệt được yêu cầu đưa ra từng dòng (hoặc khi thích hợp - ví dụ: hình ảnh bằng hình ảnh, v.v.) giải thích hoặc bình luận mà ông chủ của tôi muốn có thể đọc và theo dõi.

Vì anh ta không phải là lập trình viên, anh ta không thể làm theo mã nên muốn tất cả được dịch sang tiếng Anh.

Có ai được yêu cầu làm điều này trước đây?

Tôi đã nhận xét về tất cả các mã nguồn và đã sử dụng JSDoc để tạo tài liệu đầy đủ về tất cả các hàm, biến, v.v ... và bao gồm một ví dụ triển khai và các bản demo làm việc đầy đủ với các bình luận xuyên suốt.

Có điều gì khác tôi có thể làm để bình luận mã cho những người không lập trình không?

Đây không phải là một yêu cầu hợp lý, phải không?

CẬP NHẬT

Cuối cùng, tôi đã giải thích được tại sao đó không phải là cách sử dụng thời gian tốt để làm những gì anh ấy yêu cầu. Anh ấy là một chàng trai hợp lý, và không hiểu gì về công việc của tôi. Khi anh ấy thấy bài đăng này, tôi nghĩ rằng anh ấy nhanh chóng hiểu rằng đó không phải là một yêu cầu bình thường.

Tôi đã cung cấp tài liệu phù hợp cho một lập trình viên khác để theo dõi (JSDoc và nhận xét nội tuyến - cũng như một số lưu ý thêm về các vấn đề kỹ thuật) và sơ đồ biểu đồ dòng rất rộng về logic chính của chương trình để ông chủ của tôi theo dõi.

Cuối cùng, tất cả các bên đều hài lòng và chúng tôi đã chuyển đi.

Không , nó không phải là một yêu cầu hợp lý!

NÓI CHUYỆN NÓ RA KHỎI NÓ , hoặc nhờ người khác nói với anh ta về điều đó, bằng mọi cách. Đó là một ý tưởng phi lý, mà mặc dù có thể thực hiện được rất tốn kém để thực hiện nhưng nó không bao giờ thực sự được thực hiện. Tổng quan về các hàm và chương trình con là hợp lý, nhưng để "giải thích" mọi dòng mã thì không. Nó sẽ có hiệu quả hơn đối với anh ta để học đọc ngôn ngữ trong tay, hơn là làm điều đó.

Điều tiếp theo anh ta sẽ yêu cầu là dịch các công thức toán học, hoặc không có gì thành văn bản tiếng Anh. Mặc dù chắc chắn có thể giới thiệu nhiều chỗ cho lỗi và giải thích sai , và không bao giờ nên được thực hiện. Cũng giống như "dịch" mã sang tiếng Anh.

Bạn có tài liệu thiết kế ? Đó là những lời giải thích bằng tiếng Anh về những gì mã làm. Một người quản lý không lập trình không cần nhiều hơn thế.

Có một người quản lý vi mô của giải thưởng năm? Nghe có vẻ như ông chủ của bạn xứng đáng được đề cử. Một số người tin rằng anh ta cần hiểu mã theo từng dòng, nhưng không muốn học cách đọc trực tiếp, hoàn hảo như người quản lý vi mô như có thể tưởng tượng.

Một lợi thế của việc trở thành nhà phát triển là khó khăn trong việc hiểu mã ngăn chặn việc quản lý vi mô vượt quá một mức độ nhất định, ít nhất là ở cấp độ triển khai chi tiết, ít nhất là bởi quản lý phi kỹ thuật, bởi vì ngay cả người quản lý vi mô cốt lõi nhất cũng nhận ra rằng họ trên đầu của họ ở cấp độ đó. Nhưng thiên tài của ông chủ của bạn có thể tìm ra cách phá vỡ bức màn silicon.

Và, như một phần thưởng, nó lãng phí rất nhiều thời gian của nhà phát triển để dịch, ngay cả trước khi anh ta sử dụng bản dịch tiếng Anh để bắt đầu đề xuất các cải tiến khác nhau (tôi cho rằng anh ta biết cách viết mã tốt hơn các lập trình viên, mặc dù anh ta không thể đọc mã, và sẽ có thể chia sẻ sự khôn ngoan của anh ta ngay khi ai đó dịch nó, nếu không thì tại sao anh ta lại cần dịch từng dòng?).

Vì vậy, không, đó không phải là một yêu cầu hợp lý và tôi chưa bao giờ nghe về nó trước đây. Và tôi cảm thấy cho bạn. Tôi nghĩ mọi người có thể cần phải lặng lẽ tìm kiếm một công việc khác, bởi vì một khi anh ta bắt đầu sử dụng dịch mã làm công cụ quản lý thì có lẽ đó sẽ là một nơi tàn bạo để làm việc (er, một nơi tàn bạo hơn để làm việc).

Về mặt tích cực, có lẽ bạn có thể có được một mẫu chống mới được đặt tên theo tình huống của bạn? Làm thế nào về mô hình chống "bẩn thỉu Hungary Phrasebook", sau tiểu phẩm Monty Python nơi một người bán thuốc lá đang cố gắng giao tiếp với một người không nói tiếng Anh bằng cách sử dụng một cuốn sách cụm từ tiếng Hungary có bản dịch sai về mặt hài hước?

Ngồi xuống với anh ta và nói chuyện với anh ta thông qua 10 dòng mã. Giải thích mọi chi tiết cho đến khi cả hai bạn đồng ý anh ấy hiểu nó đến mức anh ấy muốn.

Có lẽ trải nghiệm này là tất cả những gì anh ấy đang tìm kiếm: chỉ là một ấn tượng về công việc của bạn đối với bạn và phần mềm trông như thế nào theo quan điểm của bạn. Đó là một điều tốt trong cuốn sách của tôi.

Nếu sau này, anh ấy vẫn muốn bạn tiếp tục, nói: chú ý có bao nhiêu câu hỏi tôi phải hỏi; hãy tưởng tượng nếu tôi phải giải thích tất cả những điều này mà không thể đặt câu hỏi, làm thế nào tôi có thể biết những gì cần bao gồm và những gì phải bỏ qua? Mất bao nhiêu thời gian trước khi kết quả có ích với bạn? Bây giờ có bao nhiêu dòng bạn muốn tôi làm theo cách này?

Tôi không nghĩ đó là một yêu cầu hợp lý. MÃ NGUỒN không có nghĩa là được đọc bằng tiếng Anh (hoặc bất kỳ ngôn ngữ nào khác cho vấn đề đó).

Có thể anh ấy sợ bạn sẽ làm cho mã của bạn làm điều gì đó mà anh ấy không chấp nhận hoặc không biết. Nếu đó là trường hợp, tôi không nghĩ rằng bạn có thể làm gì đó về nó. Bạn sẽ phải viết tài liệu hoặc có thể thuyết phục anh ấy / cô ấy thuê ai đó để kiểm tra mã của bạn.

Nó thực sự rất đơn giản:

• Bạn đã được tuyển dụng vì kỹ năng của bạn như là một lập trình viên
• Người quản lý của bạn không có những kỹ năng này
• Ergo, người quản lý của bạn không nên mong đợi một cách hợp lý để có thể hiểu đầy đủ những gì bạn làm

Tôi đã có một kinh nghiệm tương tự như thế này trong một công việc trước đây. Người quản lý của tôi là một kế toán viên (và do đó có định hướng chi tiết ở mức độ thấp) và không hiểu hoặc không thực sự tin tưởng vào lập trình. Cô ấy không thể hiểu rằng cô ấy, với tư cách là một người phi kỹ thuật, không nên mong đợi có thể nắm bắt được những điều vụn vặt trong những gì tôi viết. Sau nhiều yêu cầu về tài liệu quá mức và yêu cầu đào tạo người dùng không có kỹ thuật về cách quản lý và thay đổi mã (vâng, thực sự), tôi đã ngừng cố gắng để loại bỏ cô ấy, và hoàn toàn từ chối. Sự tương tự tôi thường giải thích rất đơn giản:

• Tôi không phải là kế toán
• Tôi không nên mong đợi để hiểu mọi giao dịch hoặc đăng trong tài khoản của chúng tôi
• Điều này không có nghĩa là các tài khoản sai hoặc không đáng tin, đơn giản là vì tôi không hiểu chúng
• Điều này được thực hiện bằng cách tin tưởng người biên soạn chúng

Cuối cùng, đây là điều tôi nghe có vẻ như: một người quản lý gặp khó khăn trong việc tin tưởng nhân viên của họ; hoặc lo sợ rằng họ sẽ rời đi, và nghĩ rằng đây là một cách hiệu quả để giảm thiểu chống lại nó.

Giải pháp duy nhất cho vấn đề này là ngồi xuống và giải thích lý do tại sao điều này không có ý nghĩa. Công việc của bạn là hiểu mã và làm cho người có kỹ năng tương tự có thể hiểu được mã của bạn, chứ không phải người quản lý của bạn. Cho họ xem chủ đề này có thể là một ý tưởng tốt (hoặc thực sự, thực sự khủng khiếp, tùy thuộc vào tính cách của họ).

Từng dòng, là vô lý. Những gì tôi có thể đề nghị là cung cấp để tạo tài liệu từ các bình luận và đưa cho anh ta điều đó. Điều đó là đủ cho một số khoản tài trợ và kiểm toán của Chính phủ Canada mà tôi đã làm trong quá khứ.

Anh ta sẽ không nhận được từng dòng một nhưng anh ta sẽ có được từng phương pháp mà vẫn có thể chi tiết hơn mức anh ta cần.

Một số giải pháp hiện có, tùy thuộc vào nền tảng của bạn:

• C #: lâu đài cát
• Java: javadoc
• "C ++, C, Java, Objective-C, Python, IDL (hương vị Corba và Microsoft), Fortran, VHDL, PHP, C # và ở một mức độ nào đó D." : doxygen

Nó sẽ nhanh hơn nhiều cho anh ta học đọc mã so với việc dịch toàn bộ mã của bất kỳ ứng dụng thú vị nào sang tiếng Anh. Bên cạnh đó, chúng tôi đã thử điều đó với COBOL và nó chẳng giúp ích gì cả. Nếu anh ta không sẵn lòng học hỏi, nhưng chỉ muốn làm cho anh ta không biết gì về vấn đề của người khác, thì bạn có một ông chủ nghiêm túc.

Sử dụng chuyên môn kỹ thuật của bạn để theo đuổi ông chủ của bạn.

1. Hãy cho anh ấy biết rằng sẽ mất nhiều thời gian để làm điều này như bạn đã làm để mã hóa nó ngay từ đầu (Hãy thoải mái để làm cho nó dài hơn.).
2. Hỏi anh ấy cách cập nhật tài liệu này. Thông báo cho anh ta tất cả các thay đổi mã hóa bây giờ sẽ mất ít nhất gấp đôi thời gian.
3. Nếu bạn hoặc bất kỳ ai khác tìm thấy bất kỳ lỗi nào, hãy hỏi anh ta nếu bạn nên sửa chúng ngay bây giờ hoặc đợi cho đến khi bạn hoàn thành mã hóa psuedo. Nhắc nhở anh ấy về # 1 & # 2.

Giống như tất cả các đề xuất giải pháp xấu, tốt hơn là xác định vấn đề. Có thể sếp của bạn đang gặp phải những câu hỏi kỹ thuật của quản lý cấp trên và anh ta cảm thấy lúng túng vì không thể trả lời. Có thể có một phần mã đặc biệt mà anh ấy cảm thấy quan tâm nhất, vì vậy bạn có thể giới hạn công việc khổng lồ này ở khu vực đó.

Bằng cách gửi mẫu, anh ta có thể đi đến kết luận rằng nếu bạn không hiểu cách mã hóa hoạt động (Vòng lặp là gì và nó đang làm gì với tất cả các mặt hàng này?) Thì nó không phải là ngôn ngữ của ngôn ngữ đó. tắt hiểu ứng dụng từ góc độ người dùng quyền lực. Tôi nghĩ thật công bằng khi bạn cho anh ấy biết rằng bạn muốn viết mã / gợi ý thực sự - tôi đang tìm một công việc khác.

Tại sao?

Một bình luận từng dòng không hợp lý, nhưng đây là những gì tôi hỏi: tại sao bạn muốn điều này?

Có phải vì ...

• Bạn muốn có một sự hiểu biết đầy đủ về những gì phần mềm làm (không nhất thiết phải như thế nào)?
• Bạn muốn chắc chắn một lập trình viên khác có thể nhận dự án nếu tôi rời đi?
• bạn muốn thấy rằng tôi đang làm việc thực sự?

Có thể có một mong muốn hợp lý đằng sau yêu cầu này, và bạn có thể làm cho sếp của bạn hài lòng bằng cách tìm ra điều đó và đáp ứng nhu cầu đó.

Cập nhật

Dựa trên Mikey'snhận xét, có lẽ tôi đã nói điều này một cách quá thẳng thừng. Tôi không có nghĩa là bạn nên nói "tại sao bạn muốn điều này theo nghĩa đen?", Chỉ là bạn nên tìm ra điều đó . Từ ngữ và giọng điệu tạo nên sự khác biệt lớn. Cụ thể, bạn có thể nói một cái gì đó như:

"Tôi đã suy nghĩ về yêu cầu của bạn để có một lời giải thích cho từng dòng mã. Có một chút khác thường khi làm theo cách đó. Tôi tự hỏi liệu có thể có điều gì đó tôi không truyền đạt tốt cho bạn về công việc của tôi. Bạn thực sự muốn hiểu gì về mã của chúng tôi hoặc về những gì tôi đang làm? Bạn đang cố gắng thực hiện điều gì ở đây? "

Tất nhiên, có thể ông chủ của bạn hoàn toàn không hợp lý. Nhưng nhiều khả năng là anh ta không biết yêu cầu này kỳ quặc đến mức nào và có một số mục tiêu hợp lý trong tâm trí.

Nếu không, bắt đầu đánh bóng sơ yếu lý lịch của bạn. :)

Âm thanh như một cơ hội tốt để thử lập trình biết chữ. Google nó. :)

Nhưng ... nó không nhất thiết là một yêu cầu hoàn toàn vô lý. Một phần công việc của bạn (phần quan trọng hơn, imo) là truyền đạt (các) thuật toán của bạn cho các nhà phát triển khác và, nếu cần, những người không có kỹ thuật. Các lập trình viên thiên tài đơn độc, những người không thể giao tiếp luôn luôn có vấn đề, tôi nghĩ vậy.

Cuối cùng, mã của bạn phải rõ ràng (nghĩa là: thực sự tự ghi lại tài liệu hoặc tài liệu tốt, và bằng cách "tự ghi lại tài liệu" Tôi có nghĩa là các biến và hàm có một ý nghĩa hoặc trách nhiệm và tên của chúng phản ánh rõ ràng điều đó). Sếp của bạn có thể có lý do chính đáng cho yêu cầu của mình. Có lẽ (tôi chỉ đoán ở đây) bạn hoặc người tiền nhiệm của bạn có tiếng về mã không thể xuyên thủng, dễ vỡ và đây là phương thuốc của sếp. Đó là một chút cực đoan, nhưng có thể là một bài tập hữu ích cho bạn. Tôi cho rằng anh ta biết rằng cần có thời gian để viết tài liệu tốt hơn (và nếu anh ta không, anh ta nên được giáo dục - nó giống như viết một bài viết hạn: mất nhiều thời gian để viết hơn là đọc).

Ngay cả một dòng dịch theo dòng sẽ không truyền đạt hiệu quả ý nghĩa của từng dòng mã. Một lập trình viên hiểu về một dòng mã luôn trong bối cảnh của nhiều yếu tố. Nhận được một cái gì đó giống như một đoạn mã đa luồng và bản dịch tiếng Anh sẽ không có ý nghĩa gì hơn mã thô. Hãy suy nghĩ về chức năng được trải rộng giữa nhiều chức năng / tập tin. Một số mã hoàn toàn không có ý nghĩa nếu không giải thích số lượng lớn các mã khác. Hãy thử giải thích các phần khác nhau liên quan đến việc tiêm phụ thuộc "từng dòng" và bạn sẽ thấy ý tôi là gì. Chỉ cần bất cứ điều gì vượt quá mã thủ tục chức năng của Thiên Chúa sẽ đòi hỏi một lượng kiến ​​thức lập trình sâu rộng chỉ để hiểu bản dịch tiếng Anh. Ngoài ra, hãy xem một cái gì đó đơn giản như một tuyên bố quyết định if / other. Không có từng dòng một, vì dòng tiếp theo phụ thuộc vào dữ liệu thời gian chạy. Dòng tiếp theo có thể là một trong một số khả năng.Khi bạn giải thích những gì ứng dụng của bạn làm, bạn sẽ biến PM của mình thành một lập trình viên và cả hai bạn sẽ 5 tuổi.

Vì tôi đã từng dạy lập trình, tôi sẽ rất vui khi cho nó đi.

Anh ta sẽ nhanh chóng phát hiện ra mình nhận được nhiều hơn những gì anh ta mặc cả, điều này sẽ khiến tôi buồn vì tôi thích giải thích mọi thứ :-)

Khi bạn đề cập đến 'Sếp' của bạn, đây có phải là "người quản lý cấp trung phụ trách bạn / nhóm của bạn" không? hoặc Chủ sở hữu công ty của bạn? Bạn có được trả "theo giờ" hay "tiền lương" không?

NẾU sếp của bạn là một người quản lý cấp trung có trách nhiệm, NÓI CHUYỆN VỚI BOSS CỦA TÔI, chỉ ra rằng để đáp ứng yêu cầu của sếp, năng suất của bạn đối với công ty sẽ giảm xuống còn 1/3 so với mức có thể.

NẾU sếp của bạn là "anh chàng ký séc" giải thích cho anh ta điều tương tự, chỉ là về mặt ngoại giao. Công việc của bạn đã chuyển từ "Viết mã" sang "Viết mã, viết giải thích mã, giải thích giải thích."

Một biểu đồ dòng chảy có thể sẽ có lợi hơn cho anh ta. Đây chắc chắn là một yêu cầu bất thường và không nói nhiều về anh ấy với tư cách là người quản lý.

Thực tế là sếp của bạn sẵn sàng dành thời gian để hiểu mã mà bạn đã viết, bạn có thể sử dụng vì lợi ích của mình. Hãy thử giới thiệu anh ấy với Cucumber: http://cukes.info/

và làm cho sếp của bạn viết bài kiểm tra BDD cho bạn trong tương lai.

Anh ta không nên bận tâm để biết bất kỳ điều đó. Nói với anh ta, rằng trong việc thực hiện phát triển phần mềm có thể thay đổi. Thiết kế sự kiện có thể thay đổi. Nói với anh ta về việc che giấu thông tin, đóng gói và trừu tượng.
Ông, với tư cách là một phần trong nhóm của bạn, với tư cách là khách hàng của mã của bạn, theo nghĩa rộng hơn, chỉ nên làm việc với sự trừu tượng hóa rõ ràng, ở mức độ cao về những gì mã của bạn làm. Giống như bất kỳ lớp mã nào của bạn hoạt động với lớp mã khác của người khác. Biết nhiều hơn thế, sẽ chỉ làm anh ta chậm lại và mạo hiểm để anh ta đưa ra các giả định dựa trên hoạt động bên trong của mã của bạn. Những giả định đó sẽ chấm dứt, khi bạn phải thay đổi mã của mình, điều này sẽ trở thành một vấn đề, nếu anh ta xây dựng bất kỳ loại hệ thống hoặc quy trình nào dựa trên chúng.
Và cũng phải làm loại công việc này sẽ làm giảm hiệu quả của bạn. Bạn không chỉ phải thực hiện các thay đổi tiếp theo ở hai nơi khác nhau mà còn ảnh hưởng tiêu cực đến tinh thần làm việc của bạn, điều này sẽ làm giảm sản lượng của bạn hơn nữa.

Vẻ đẹp của tiếng Anh là obfucates đẹp. Nếu bạn sử dụng điều này cho lợi thế của mình, bạn có thể không bao giờ phải đối phó với loại yêu cầu này nữa. Tôi sẽ lấy một đoạn mã nhỏ làm mẫu nhưng một đoạn rất trừu tượng và không dễ hiểu chút nào. Sau đó tôi sẽ viết lên những bình luận bằng tiếng Anh kỹ thuật như thể bạn đang viết nó cho một chương trong một cuốn sách lập trình. Càng theo dõi càng lâu và càng phức tạp. Nói cho anh ấy biết bạn mất bao nhiêu giờ để ghi lại tính năng này. Sau đó giải thích rằng đó chỉ là 1/10 của 1% (sử dụng số liệu thực tế dựa trên các dòng mã nếu bạn có thể, chúng có thể tệ hơn mức này) của cơ sở mã thực tế. Khi anh ta nhận ra rằng anh ta không biết bản dịch tiếng Anh nói gì và sẽ mất 20.000 giờ để làm tài liệu này, anh ta sẽ rút lui khá nhanh. Nhưng rất nghiêm túc cố gắng để hoàn thành nhiệm vụ của mình. Đừng thử điều này nếu bạn không thể thực hiện điều đó và anh ta nghi ngờ bạn đang chơi anh ta.

Điều này trông giống như một ứng cử viên cho một dải Dilbert -ông chủ tóc nhọn vấn đề kỳ nghỉ đặc biệt ! Yêu cầu của ông chắc chắn không âm thanh hợp lý ở cái nhìn đầu tiên.

Hài hước sang một bên, cố gắng tìm hiểu những gì anh ta thực sự cần, và tại sao, sau đó khuyên anh ta về những gì sẽ tốn bằng đô la hoặc giờ để cung cấp cho anh ta, và để anh ta quyết định nếu anh ta muốn chi nhiều tiền cho nó.

Đối với bản thân bạn, hãy đếm số giờ bạn sẽ đáp ứng yêu cầu có vẻ kỳ quái của anh ấy và sau đó xác định xem bạn có nên đầu tư một phần thời gian đó để tìm một công việc mới làm việc cho một chủ nhân sẵn sàng đối xử với bạn không như một chuyên gia!

Đưa anh ta vào văn phòng của bạn và cho anh ta một chuyến tham quan mã của bạn.

Anh ta sẽ nhận ra một phần thông qua việc anh ta đưa ra một yêu cầu vô lý, và anh ta sẽ bỏ đi và không bao giờ làm phiền bạn nữa.

Nếu bạn không đưa ra yêu cầu của anh ấy để giúp anh ấy cố gắng hiểu mã của bạn, anh ấy sẽ tìm những cách khác nhau nhưng không kém phần ngớ ngẩn để chọc bạn.

Đây là một trường hợp mà sự xoa dịu hoạt động tốt hơn mài mòn.

Sẽ thật tuyệt nếu chúng tôi có một dịch giả "Ngôn ngữ X sang tiếng Anh" thực hiện điều này. Sau đó, người ta có thể cười và nói, không vấn đề gì, ông chủ, bạn sẽ có điều đó trong một phút. Và sau đó xuất hiện một thư với một vài megabyte văn bản có nội dung:

• Đặt một mảng số nguyên mới có 20 phần tử.
• Đặt x là biến để lưu số nguyên.
• Đặt x thành 0
• Trong khi x nhỏ hơn 20, hãy làm những gì được quy định trong 2 dòng tiếp theo
• đặt phần tử mảng của a với chỉ số x thành kết quả của việc gọi nThPrime với đối số x + 1
• tăng x 1
• ....

Một lựa chọn khác là đề xuất lập trình trong Shakespeare từ đó.

Sếp của tôi muốn một lời giải thích bằng tiếng Anh từng dòng về mã của chúng tôi

Khó khăn.

Vì anh ta không phải là lập trình viên, anh ta không thể làm theo mã, vì vậy muốn tất cả được dịch sang tiếng Anh.

Nếu anh ta không phải là một lập trình viên, anh ta không nên đọc mã. Ở tất cả.

Cung cấp tài liệu cấp cao thay thế.

Đây không phải là một yêu cầu hợp lý, phải không?

Không.

Là một lập trình viên, bạn thực sự có "hai" công việc.

Đầu tiên là tạo ra các chương trình tốt. Thứ hai là "bán" chúng cho khách hàng trong và ngoài công ty.

Yêu cầu của sếp "làm tổn thương" công việc đầu tiên của bạn. Phải mất nhiều thời gian hơn để tài liệu chương trình của bạn. Mặt khác, anh ấy thực sự khiến bạn làm việc chăm chỉ hơn trong công việc "thứ hai" của mình.

Sếp của bạn đang yêu cầu bạn ghi lại chương trình bằng tiếng Anh vì lợi ích của mình và có lẽ vì lợi ích của những người mà anh ta phải đối phó trong và ngoài công ty. Nếu bạn giúp anh ta thực hiện công việc của mình, điều đó sẽ mang lại lợi ích cho bạn về lâu dài, khi bạn yêu cầu anh ta cho thêm phần cứng, nhân sự hoặc tiền để tăng lương. Rốt cuộc, anh ấy yêu cầu bạn làm thêm công việc.

Tôi nghĩ rằng BDD sẽ phù hợp với vấn đề này, mặc dù có vẻ như dự án của bạn sắp hoàn thành, vì vậy rất khó để thực hiện nó ngay bây giờ, vì vậy nó giống như để tham khảo trong tương lai.

Với các trường hợp sử dụng BDD được mô tả là các tài liệu có thể đọc được, sau đó được dịch thành các kiểm tra chức năng tự động.

Có lẽ, yêu cầu này là thời điểm tốt để tìm hiểu những thứ như ANTLR . Lấy ANTLR, lấy ngữ pháp ngôn ngữ của bạn, phân tích tất cả mã bạn có, duyệt qua AST tạo mô tả dựa trên mẫu cho mỗi nút, do đó i++được mô tả là increase i by 1 using postfix increment operator. Điều đó nên thực sự hài hước. Sếp của bạn cũng có thể muốn đưa công cụ này vào tập lệnh xây dựng, vì vậy mỗi khi bạn thực hiện bất kỳ thay đổi nào, anh ta sẽ nhận được e-mail ~ 20 MB mô tả phiên bản mới làm gì.

PS đùa thôi, anh ta là một thằng ngốc.

Mặc dù tôi đồng ý rằng đây là một yêu cầu không hợp lý, nhưng sếp của bạn có thể đánh giá cao thứ gì đó như đầu ra của Docco , phân tách các nhận xét về mã và từng dòng hoặc mệnh đề của bạn thành đầu ra HTML hai cột, với mã trên một bên và văn xuôi bên kia. Bạn phải tự gõ các bình luận, tất nhiên, nhưng phần trình bày khá IMHO, ngay cả đối với những người đọc không có kỹ thuật. Ví dụ, hãy xem phần nhận xét từng dòng của mã được chú thích cho Underscore.js . Có phiên bản Python và shell script.

Có thể ông chủ của bạn chỉ là người không hiểu biết và bị đe dọa, nhưng thực sự là một người hợp lý. Nếu vậy, lý luận với anh ấy / cô ấy có thể có hiệu quả - một cuộc trò chuyện ngẫu nhiên nơi bạn hứa sẽ cung cấp "những gì anh ấy thực sự muốn" tức là; một hướng dẫn văn xuôi cho những gì chương trình đang làm.

Nếu nó đi xuống "đường của tôi hoặc đường cao tốc", hãy kiểm tra khí của bạn ngay bây giờ.

Bạn có thể viết một số thử nghiệm chấp nhận bằng cách sử dụng khung thiết kế hướng hành vi như dưa chuột ? Điều đó sẽ không giải thích mã; nó sẽ giải thích những gì nó làm, và bằng ngôn ngữ tự nhiên. Nó cũng có lợi ích là có thể thực thi được, vì vậy bạn luôn có thể chắc chắn rằng tài liệu được cập nhật, bởi vì nếu không, trình chạy thử nghiệm sẽ có màu đỏ.

Kiểm tra video giới thiệu. Có lẽ đó là một sự chuyển hướng tốt trong khi bạn tìm thấy một ông chủ mới ... ;-)

Người quản lý của bạn gần như chắc chắn đau khổ vì thực tế là anh ta không hiểu những gì mọi người làm mà anh ta đang quản lý và anh ta không có nền tảng để hiểu kết quả mà họ tạo ra.

Tôi nghi ngờ anh ấy nghĩ giải pháp này rất kỹ lưỡng, và nó có vẻ hợp lý với anh ấy từ cái nhìn đầu tiên. Nhưng đó phần lớn là vì anh ta không hiểu mã lập trình thực sự là gì.

Bất kỳ lập trình viên nào cũng hiểu sự vô lý của yêu cầu này, nhưng chúng tôi làm bởi vì chúng tôi biết một cách trực giác rằng một khi bạn vượt qua ngôn ngữ, tất cả những gì được tiết lộ là thuật toán, cũng khó hiểu không kém.

// Set s to the first address in the server list
server_info *s = cmd->servers;
// Loop until s is NULL
while (s) {
    // call the server's init function passing our current ID and address
    s->init(proc->id,*addr);
    // call log::info with our custom message
    log::info("Starting server %s",s->name);
    // Set s to the value returned by the server's next() function
    s=s->next();
} // end of loop

Vấn đề ở đây là trong khi các ý kiến ​​giải thích mỗi dòng làm gì, bạn vẫn không biết mã thực sự làm gì trừ khi bạn hiểu tất cả các hàm ý là gì. Thật rõ ràng nếu bạn là một lập trình viên và đã thấy mẫu này trước đó; nhưng hãy thể hiện điều này với một người chỉ hiểu bán hàng và anh ta sẽ bối rối sau khi đọc những bình luận như trước đây.

Bạn thực sự có thể tiết kiệm thời gian bằng cách dạy cho sếp của bạn một số chương trình cơ bản. Nếu anh ấy muốn đọc mã của bạn, hãy cho anh ấy các công cụ để có thể làm như vậy. Hầu hết các ngôn ngữ đều khá nhỏ gọn theo cú pháp và việc học cấu trúc chỉ mất một hoặc hai giờ. Anh ấy gần như chắc chắn sẽ bỏ cuộc sau vài ngày, nhưng ít nhất anh ấy sẽ biết những gì anh ấy đang truyền lại, và quan trọng hơn là tại sao anh ấy không muốn đọc mã của bạn.

IMHO ... nếu anh ấy chịu trách nhiệm hoàn thành nhiệm vụ, anh ấy nên biết nó hoạt động như thế nào ... :)