เจ้านายของฉันต้องการคำอธิบายภาษาอังกฤษแบบบรรทัดต่อบรรทัดของรหัสของเรา

ฉันถูกขอให้ระบุบรรทัดต่อบรรทัด (หรือตามความเหมาะสม - ตัวอย่างเช่นรูปภาพต่อรูปภาพ ฯลฯ ) หรือคำอธิบายที่หัวหน้าของฉันต้องการให้สามารถอ่านและปฏิบัติตามได้

เนื่องจากเขาไม่ใช่โปรแกรมเมอร์เขาจึงไม่สามารถทำตามรหัสได้ดังนั้นจึงต้องการให้มันแปลเป็นภาษาอังกฤษทั้งหมด

มีใครเคยขอให้ทำเช่นนี้มาก่อนหรือไม่

ฉันได้แสดงความคิดเห็นในทุกซอร์สโค้ดและใช้JSDocเพื่อสร้างเอกสารทั้งหมดของฟังก์ชั่นตัวแปร ฯลฯ ... และรวมถึงตัวอย่างการใช้งานและการสาธิตการทำงานเต็มรูปแบบที่มีความคิดเห็นตลอด

มีอะไรอีกบ้างที่ฉันสามารถทำได้เพื่อแสดงความคิดเห็นรหัสสำหรับผู้ที่ไม่ใช่โปรแกรมเมอร์?

นี่ไม่ใช่คำขอที่สมเหตุสมผลใช่ไหม

UPDATE

ในท้ายที่สุดฉันพยายามอธิบายว่าทำไมการใช้เวลาทำสิ่งที่เขาถามไม่ดี เขาเป็นคนที่เหมาะสมและไม่เข้าใจในสิ่งที่งานของฉันเกี่ยวข้อง เมื่อเขาเห็นโพสต์นี้ฉันคิดว่าเขาเข้าใจอย่างรวดเร็วว่าไม่ใช่คำขอปกติ

ฉันได้จัดทำเอกสารที่เหมาะสำหรับโปรแกรมเมอร์คนอื่น ๆ ที่จะติดตาม (JSDoc และความคิดเห็นแบบอินไลน์ - รวมถึงบันทึกเพิ่มเติมบางอย่างเกี่ยวกับปัญหาทางเทคนิค) และไดอะแกรมแผนภูมิการไหลที่กว้างมากของตรรกะหลักของโปรแกรมสำหรับเจ้านายของฉัน

ในท้ายที่สุดทุกฝ่ายพอใจและเราก็เดินหน้าต่อไป

ไม่มันไม่ใช่คำขอที่สมเหตุสมผล!

พูดคุยกับเขาหรือให้คนอื่นพูดกับเขาด้วยวิธีการทั้งหมด นั่นเป็นความคิดที่ไม่มีเหตุผลซึ่งแม้ว่าจะทำได้จริงราคาแพงก็ไม่ควรทำจริง ภาพรวมของฟังก์ชั่นและรูทีนย่อยมีความสมเหตุสมผล แต่เพื่อ "อธิบาย" ทุกบรรทัดโค้ดไม่ได้ มันจะมีประสิทธิภาพมากกว่าสำหรับเขาที่จะเรียนรู้การอ่านภาษาในมือมากกว่าที่จะทำ

สิ่งต่อไปที่เขาจะขอคือการแปลสูตรคณิตศาสตร์หรืออะไรก็ตามที่เป็นข้อความภาษาอังกฤษ แม้ว่าเป็นไปได้อย่างแน่นอนที่แนะนำห้องพักมากสำหรับข้อผิดพลาดและการตีความที่ผิดและไม่ควรทำ เช่นเดียวกับรหัส "แปล" เป็นภาษาอังกฤษ

คุณมีเอกสารการออกแบบหรือไม่? เหล่านี้คือคำอธิบายภาษาอังกฤษเกี่ยวกับสิ่งที่รหัสทำ ผู้จัดการที่ไม่ใช่การเขียนโปรแกรมไม่ควรต้องการมากกว่านั้น

มีผู้จัดการรายย่อยประจำปีหรือไม่ ดูเหมือนว่าเจ้านายของคุณสมควรได้รับการเสนอชื่อ คนที่เชื่อว่าเขาต้องการความเข้าใจในระดับบรรทัดต่อบรรทัด แต่ไม่ต้องการที่จะเรียนรู้วิธีการอ่านโดยตรงนั้นเป็นเรื่องสมบูรณ์แบบเท่าที่ผู้จัดการไมโครสามารถจินตนาการได้

ข้อดีอย่างหนึ่งของการเป็นนักพัฒนาคือความยากในการทำความเข้าใจโค้ดป้องกันการจัดการไมโครเกินกว่าระดับที่กำหนดอย่างน้อยอย่างน้อยในระดับการใช้งานอย่างน้อยโดยการจัดการที่ไม่ใช่ด้านเทคนิคเพราะแม้แต่ผู้จัดการไมโครคอร์ที่เข้าใจยากที่สุด เหนือศีรษะในระดับนั้น แต่อัจฉริยะของเจ้านายของคุณอาจพบวิธีที่จะทำลายม่านซิลิคอน

และเป็นโบนัสมันเสียเวลานักพัฒนาอย่างมากในการแปลแม้กระทั่งก่อนที่เขาจะใช้การแปลภาษาอังกฤษเพื่อเริ่มแนะนำการปรับปรุงต่าง ๆ (ฉันคิดว่าเขารู้วิธีการเขียนโค้ดได้ดีกว่าโปรแกรมเมอร์แม้ว่าเขาจะไม่สามารถอ่านรหัสและจะสามารถแบ่งปันภูมิปัญญาของเขาได้ทันทีที่มีคนแปลมันมิฉะนั้นทำไมเขาต้องแปลทุกบรรทัด?)

ดังนั้นไม่ใช่มันไม่ใช่คำขอที่สมเหตุสมผลและฉันไม่เคยได้ยินมาก่อน และฉันรู้สึกถึงคุณ ฉันคิดว่าทุกคนอาจต้องเริ่มมองหางานอื่นอย่างเงียบ ๆ เพราะเมื่อเขาเริ่มใช้การแปลรหัสเป็นเครื่องมือในการจัดการมันอาจจะเป็นสถานที่ที่โหดร้ายในการทำงาน (เอ้อเป็นสถานที่ทำงานที่โหดร้ายกว่า)

ในด้านบวกคุณอาจได้รูปแบบการต่อต้านแบบใหม่ที่ตั้งชื่อตามสถานการณ์ของคุณ? วิธีการเกี่ยวกับรูปแบบการต่อต้าน "Dirty Hungarian Phrasebook" หลังจาก Monty Python เสียขวัญที่ผู้ค้ายาสูบพยายามสื่อสารกับคนที่ไม่พูดภาษาอังกฤษโดยใช้หนังสือวลีภาษาฮังการีที่มีคำแปลที่ผิดอย่างตลก ๆ ?

นั่งลงกับเขาแล้วคุยกับเขาผ่านรหัส 10 บรรทัด อธิบายทุกรายละเอียดจนกว่าคุณทั้งคู่จะเห็นว่าเขาเข้าใจในขอบเขตที่เขาต้องการ

บางทีประสบการณ์นี้อาจเป็นสิ่งที่เขากำลังมองหา: เป็นเพียงความประทับใจในสิ่งที่งานของคุณดูเหมือนกับคุณและสิ่งที่ซอฟท์แวร์มองจากมุมมองของคุณ นั่นเป็นสิ่งที่ดีในหนังสือของฉัน

ถ้าหลังจากนี้เขายังต้องการให้คุณพูดต่อไป: สังเกตว่ามีคำถามกี่ข้อที่ฉันต้องถาม ลองนึกภาพถ้าฉันจะต้องอธิบายทั้งหมดนี้โดยไม่สามารถถามคำถามได้ฉันจะรู้ได้อย่างไรว่าควรรวมอะไรและจะออกไปอย่างไร จะใช้เวลานานเท่าใดก่อนที่ผลลัพธ์จะเป็นประโยชน์สำหรับคุณ ทีนี้คุณอยากให้ฉันทำในลักษณะนี้กี่บรรทัด?

ฉันไม่คิดว่ามันเป็นคำขอที่สมเหตุสมผล รหัสแหล่งที่มาไม่ได้หมายถึงให้อ่านเป็นภาษาอังกฤษ (หรือภาษาอื่น ๆ สำหรับเรื่องนั้น)

บางทีเขาอาจกลัวว่าคุณกำลังจะทำให้โค้ดของคุณทำอะไรบางอย่างที่เขาไม่เห็นด้วยหรือรู้ตัว หากเป็นกรณีนี้ฉันไม่คิดว่าจะมีสิ่งใดที่คุณสามารถทำได้ คุณจะต้องเขียนเอกสารหรืออาจโน้มน้าวให้เขา / เธอจ้างคนเพื่อตรวจสอบรหัสของคุณ

มันง่ายมากจริงๆ:

• คุณได้รับการว่าจ้างเนื่องจากทักษะของคุณในฐานะโปรแกรมเมอร์
• ผู้จัดการของคุณไม่มีทักษะเหล่านี้
• ดังนั้นผู้จัดการของคุณไม่ควรคาดหวังว่าจะสามารถเข้าใจสิ่งที่คุณทำ

ฉันเคยมีประสบการณ์แบบนี้กับงานก่อนหน้านี้ ผู้จัดการของฉันเป็นนักบัญชี (และให้รายละเอียดในระดับต่ำมาก) และไม่เข้าใจหรือไม่ไว้วางใจการเขียนโปรแกรมอย่างแท้จริง เธอไม่สามารถเข้าใจได้ว่าเธอในฐานะคนที่ไม่ใช่ช่างเทคนิคไม่ควรคาดหวังว่าจะสามารถเข้าใจสิ่งที่ฉันเขียนได้ หลังจากมีการร้องขอเอกสารจำนวนมากและคำขอให้ฝึกอบรมผู้ใช้ที่ไม่ใช่ด้านเทคนิคเกี่ยวกับวิธีจัดการและแก้ไขรหัส (ใช่จริง ๆ ) ฉันหยุดพยายามที่จะโกงเธอและปฏิเสธทันที การเปรียบเทียบที่ฉันเคยอธิบายนั้นง่ายมาก:

• ฉันไม่ใช่นักบัญชี
• ฉันไม่ควรคาดหวังว่าจะเข้าใจการทำธุรกรรมหรือการโพสต์ทุกรายการในบัญชีของเรา
• นี่ไม่ได้หมายความว่าบัญชีผิดหรือไม่น่าไว้วางใจเพียงเพราะฉันไม่เข้าใจ
• สิ่งนี้เกิดขึ้นได้โดยการไว้วางใจคนที่รวบรวมพวกเขา

ในตอนท้ายของทั้งหมดนี่คือสิ่งที่ฉันชอบ: ผู้จัดการที่มีปัญหาในการไว้วางใจพนักงานของพวกเขา; หรือกลัวว่าพวกเขาจะจากไปและคิดว่านี่เป็นวิธีที่มีประสิทธิภาพในการลดความขัดแย้ง

ทางออกเดียวของสิ่งนี้คือนั่งลงและอธิบายว่าทำไมจึงไม่สมเหตุสมผล เป็นหน้าที่ของคุณที่จะต้องเข้าใจรหัสและทำให้คนที่มีทักษะคล้าย ๆ กันตั้งค่าให้คุณเข้าใจมันไม่ใช่ผู้จัดการของคุณ การแสดงหัวข้อนี้อาจเป็นความคิดที่ดี (หรือน่ากลัวจริงๆขึ้นอยู่กับบุคลิกภาพของพวกเขา)

ทีละบรรทัดไร้สาระ สิ่งที่ฉันอาจแนะนำคือเสนอให้สร้างเอกสารจากความคิดเห็นและบอกเขาว่า นั่นก็เพียงพอแล้วสำหรับรัฐบาลแคนาดาหลายทุนและการตรวจสอบที่ฉันเคยทำมาในอดีต

เขาจะไม่ได้รับทีละบรรทัด แต่เขาจะได้รับวิธีการโดยวิธีซึ่งยังคงควรจะละเอียดกว่าที่เขาต้องการ

โซลูชันที่มีอยู่บางตัวขึ้นอยู่กับแพลตฟอร์มของคุณ:

• C #: sandcastle
• Java: javadoc
• "C ++, C, Java, Objective-C, Python, IDL (รสชาติของ Corba และ Microsoft), Fortran, VHDL, PHP, C #, และในระดับหนึ่ง D. " : doxygen

มันจะเร็วกว่ามากสำหรับเขาที่จะเรียนรู้ที่จะอ่านโค้ดมากกว่าที่จะเป็นการแปลรหัสทั้งหมดของแอปพลิเคชันที่น่าสนใจใด ๆ ให้เป็นภาษาอังกฤษ นอกจากนี้เราลองใช้ COBOL และมันก็ไม่ได้ช่วยอะไรเลย หากเขาไม่เต็มใจที่จะเรียนรู้ แต่ต้องการที่จะทำให้เขาไม่รู้ถึงปัญหาของคนอื่นคุณมีหัวหน้าที่มีความสำคัญ

ใช้ความเชี่ยวชาญด้านเทคนิคของคุณเพื่อไล่ตามเจ้านายของคุณ

1. ให้เขารู้ว่าจะต้องใช้เวลานานเท่าที่จะทำได้เช่นเดียวกับที่คุณทำรหัสในตอนแรก (รู้สึกอิสระที่จะทำให้มันยาวขึ้น)
2. ถามเขาว่าเอกสารนี้เป็นเอกสารที่ทันสมัยหรือไม่ แจ้งให้เขาทราบการเปลี่ยนแปลงการเข้ารหัสทั้งหมดจะใช้เวลาอย่างน้อยสองเท่า
3. หากคุณหรือคนอื่น ๆ พบข้อผิดพลาดใด ๆ ถามเขาว่าคุณควรแก้ไขพวกเขาในขณะนี้หรือรอจนกว่าคุณจะเสร็จสิ้นการเข้ารหัส psuedo เตือนเขาเกี่ยวกับ # 1 & # 2

เช่นเดียวกับข้อเสนอแนะวิธีแก้ปัญหาที่ไม่ดีจะเป็นการดีกว่าที่จะระบุปัญหา บางทีเจ้านายของคุณอาจโดนคำถามทางเทคนิคโดยผู้บริหารระดับสูงและเขาก็รู้สึกอายเพราะเขาไม่สามารถตอบได้ อาจมีส่วนใดส่วนหนึ่งของรหัสที่เขารู้สึกเป็นห่วงมากที่สุดดังนั้นคุณสามารถ จำกัด การทำงานขนาดใหญ่นี้ไปยังพื้นที่นั้นได้

โดยการส่งตัวอย่างเขาอาจสรุปได้ว่าถ้าคุณไม่เข้าใจว่าการเขียนโค้ดทำงานอย่างไร (ลูปคืออะไรและมันทำอะไรกับไอเท็มเหล่านี้ทั้งหมด) มันไม่สำคัญว่ามันจะเป็นภาษาอะไร การทำความเข้าใจแอปพลิเคชันจากมุมมองของผู้ใช้ระดับสูง ฉันคิดว่ามันยุติธรรมสำหรับคุณที่จะให้เขารู้ว่าคุณควรจะเขียนโค้ด / คำใบ้จริง ๆ - ฉันกำลังมองหางานอื่น

ทำไม?

ความเห็นทีละบรรทัดไม่สมเหตุสมผล แต่นี่คือสิ่งที่ฉันถาม: ทำไมคุณต้องการสิ่งนี้

เป็นเพราะ ...

• คุณต้องการความเข้าใจอย่างถ่องแท้ว่าซอฟต์แวร์นี้ทำอะไรได้บ้าง
• คุณต้องการให้แน่ใจว่าโปรแกรมเมอร์อื่นสามารถรับโครงการได้ถ้าฉันออกไป?
• คุณต้องการที่จะเห็นว่าฉันกำลังทำงานจริงหรือไม่

อาจมีความปรารถนาที่สมเหตุสมผลตามคำขอนี้และคุณอาจทำให้เจ้านายของคุณมีความสุขโดยการหาและตอบสนองความต้องการนั้น

ปรับปรุง

จากMikey'sความคิดเห็นฉันอาจกล่าวว่านี่เล็กน้อยเกินไปโดยตรง ผมไม่ได้หมายความว่าคุณอย่างแท้จริงควรจะพูดว่า "ทำไมคุณถึงอยากให้เรื่องนี้?" เพียงแค่ว่าคุณควรจะพบว่า การใช้ถ้อยคำและน้ำเสียงสร้างความแตกต่างอย่างมาก โดยเฉพาะคุณสามารถพูดบางสิ่งเช่น:

"ฉันกำลังคิดถึงคำขอของคุณที่จะมีคำอธิบายเกี่ยวกับโค้ดทุกบรรทัดมันผิดปกตินิดหน่อยที่จะทำสิ่งนั้นฉันสงสัยว่าบางทีอาจมีบางอย่างที่ฉันไม่สามารถสื่อสารกับคุณเกี่ยวกับงานของฉันได้ อะไรคือสิ่งที่คุณต้องการเข้าใจเกี่ยวกับรหัสของเราหรือสิ่งที่ฉันกำลังทำอยู่คุณพยายามทำอะไรให้สำเร็จที่นี่?

แน่นอนเป็นไปได้ว่าหัวหน้าของคุณไม่มีเหตุผลทั้งหมด แต่มีแนวโน้มว่าเขาจะไม่รู้ว่าคำขอนี้เป็นไปต่างประเทศและมีเป้าหมายที่สมเหตุสมผล

ถ้าไม่เริ่มขัดประวัติของคุณ :)

ฟังดูเหมือนเป็นโอกาสที่ดีที่จะลองเขียนโปรแกรมความรู้ Google มัน :)

แต่ ... มันไม่ได้เป็นคำขอที่ไม่สมเหตุสมผลทั้งหมด ส่วนหนึ่งของงานของคุณ (ส่วนที่สำคัญยิ่งกว่า imo) คือการสื่อสารอัลกอริธึมของคุณกับนักพัฒนาคนอื่น ๆ และถ้าจำเป็นคนที่ไม่ใช่ด้านเทคนิค โปรแกรมเมอร์อัจฉริยะผู้โดดเดี่ยวที่ไม่สามารถสื่อสารได้มักเป็นปัญหาเสมอไป

ไปสิ้นสุดที่รหัสของคุณควรจะยี้ชัดเจน (หมายถึง: ทั้งอย่างแท้จริงตนเอง documenting หรือดีเอกสารและ "การจัดเก็บเอกสารด้วยตนเอง" ผมหมายความว่าตัวแปรและฟังก์ชั่นมีหนึ่งความหมายหรือความรับผิดชอบและชื่อของพวกเขาสะท้อนให้เห็นว่าอย่างชัดเจน) เจ้านายของคุณอาจมีเหตุผลที่ดีสำหรับคำขอของเขา บางที (ฉันแค่เดาที่นี่) คุณหรือบรรพบุรุษของคุณมีชื่อเสียงในเรื่องรหัสที่ไม่น่าเชื่อถือและเปราะบางและนี่คือวิธีการรักษาของเจ้านายคุณ มันค่อนข้างสุดขีด แต่อาจเป็นการออกกำลังกายที่มีประโยชน์สำหรับคุณ ฉันคิดว่าเขารู้ว่าต้องใช้เวลาในการเขียนเอกสารที่ดีกว่า (และถ้าเขาไม่ทำเขาควรได้รับการศึกษา - มันเหมือนกับการเขียนบทความคำศัพท์: ใช้เวลาในการเขียนนานกว่าการอ่าน)

แม้แต่การแปลบรรทัดโดยบรรทัดจะไม่สามารถสื่อความหมายของแต่ละบรรทัดได้อย่างมีประสิทธิภาพ ความเข้าใจในโปรแกรมเมอร์ของบรรทัดของรหัสอยู่เสมอในบริบทของปัจจัยหลายอย่าง ทำความคุ้นเคยกับโค้ดที่มีหลายเธรดและการแปลภาษาอังกฤษจะไม่สมเหตุสมผลเกินกว่ารหัสดิบ ลองคิดถึงฟังก์ชั่นการทำงานที่หลากหลายระหว่างฟังก์ชั่น / ไฟล์ รหัสบางอย่างไม่สมเหตุสมผลโดยไม่ต้องอธิบายรหัสอื่นจำนวนมาก พยายามอธิบายส่วนต่าง ๆ ที่เกี่ยวข้องในการฉีดพึ่งพา "บรรทัดต่อบรรทัด" และคุณจะเห็นสิ่งที่ฉันหมายถึง อะไรก็ตามที่เกินกว่ารหัสขั้นตอนการทำงานของพระเจ้าจะต้องใช้ความรู้การเขียนโปรแกรมจำนวนมากเพื่อทำความเข้าใจการแปลภาษาอังกฤษ นอกจากนี้ให้ดูสิ่งที่ง่ายเหมือนคำสั่งการตัดสินใจ if / else ไม่มีบรรทัดต่อบรรทัด เนื่องจากบรรทัดถัดไปขึ้นอยู่กับข้อมูลเวลาทำงาน บรรทัดถัดไปอาจเป็นหนึ่งในหลาย ๆ ทางที่เป็นไปได้เมื่อถึงเวลาที่คุณอธิบายว่าใบสมัครของคุณทำอะไรคุณจะทำให้ PM ของคุณเป็นโปรแกรมเมอร์และคุณจะมีอายุมากกว่า 5 ปี

ตั้งแต่ฉันเคยสอนการเขียนโปรแกรมฉันจะมีความสุขเกินไปที่จะให้มันไป

เขาจะพบว่าเขาได้รับมากกว่าที่เขาต่อรองอย่างรวดเร็วซึ่งจะทำให้ฉันเศร้าเพราะฉันชอบอธิบายสิ่งต่าง ๆ:-)

เมื่อคุณอ้างถึง 'บอส' ของคุณนี่คือ "ผู้จัดการระดับกลางที่ดูแลคุณ / ทีมของคุณ"? หรือเจ้าของ บริษัท ของคุณ? คุณจ่าย "รายชั่วโมง" หรือ "เงินเดือน" หรือไม่?

หากเจ้านายของคุณเป็นผู้จัดการระดับกลางที่มีความรับผิดชอบพูดคุยกับเจ้านายของเขาชี้ให้เห็นว่าเพื่อตอบสนองความต้องการของหัวหน้างานของคุณประสิทธิภาพการทำงานของ บริษัท ของคุณจะถูกลดลงเหลือ 1/3 ของสิ่งที่เป็นไปได้

หากเจ้านายของคุณคือ "คนที่ลงนามในเช็ค" อธิบายให้เขาฟังอย่างเดียวกัน งานของคุณได้ไปจาก "เขียนรหัส" ถึง "เขียนรหัสเขียนคำอธิบายของรหัสอธิบายคำอธิบาย"

แผนภูมิการไหลอาจเป็นประโยชน์กับเขามากกว่า นี่เป็นคำขอที่ผิดปกติและไม่ได้พูดถึงเขามากนักในฐานะผู้จัดการ

ความจริงที่ว่าเจ้านายของคุณยินดีที่จะใช้เวลาทำความเข้าใจรหัสที่คุณเขียนคุณสามารถใช้เพื่อประโยชน์ของคุณ ลองแนะนำเขากับ Cucumber: http://cukes.info/

และทำให้หัวหน้าของคุณเขียนการทดสอบ BDD ให้คุณในอนาคต

เขาไม่ควรที่จะรู้เรื่องใด ๆ บอกเขาว่าในการนำการพัฒนาซอฟต์แวร์ไปใช้อาจมีการเปลี่ยนแปลง การออกแบบกิจกรรมอาจมีการเปลี่ยนแปลง บอกเขาเกี่ยวกับการซ่อนข้อมูลการห่อหุ้มและสิ่งที่เป็นนามธรรม
ในฐานะที่เป็นส่วนหนึ่งของทีมของคุณในฐานะที่เป็นลูกค้าของรหัสของคุณในวงกว้างคุณควรทำงานกับสิ่งที่เป็นนามธรรมในระดับสูงอย่างชัดเจนว่าโค้ดของคุณทำอะไร วิธีเดียวกับที่เลเยอร์ของโค้ดของคุณทำงานร่วมกับเลเยอร์อื่นของโค้ดของคนอื่น การรู้จักอะไรมากกว่านั้นจะทำให้เขาช้าลงและเสี่ยงต่อการตั้งสมมติฐานตามการทำงานภายในของรหัสของคุณ สมมติฐานเหล่านั้นจะยุติลงเมื่อคุณต้องเปลี่ยนรหัสซึ่งจะกลายเป็นปัญหาหากเขาสร้างระบบหรือกระบวนการใด ๆ ขึ้นอยู่กับพวกเขา
และการต้องทำงานประเภทนี้จะช่วยลดประสิทธิภาพของคุณ ไม่เพียง แต่คุณจะต้องทำการเปลี่ยนแปลงครั้งต่อไปในสองสถานที่ต่าง ๆ แต่มันจะส่งผลเสียต่อขวัญและกำลังใจในการทำงานของคุณซึ่งจะลดผลงานของคุณลงไปอีก

ความงามของภาษาอังกฤษคือสิ่งที่คลุมเครืออย่างสวยงาม หากคุณใช้สิ่งนี้เพื่อผลประโยชน์ของคุณคุณอาจไม่เคยจัดการกับคำขอประเภทนี้อีกเลย ฉันจะเอาโค้ดชิ้นเล็ก ๆ เป็นตัวอย่าง แต่อันที่เป็นนามธรรมและไม่เข้าใจง่าย จากนั้นฉันจะเขียนความคิดเห็นเป็นภาษาอังกฤษเชิงเทคนิคราวกับว่าคุณกำลังเขียนเป็นบทในหนังสือการเขียนโปรแกรม ยิ่งติดตามและยาวขึ้นซับซ้อนยิ่งดี บอกเขาว่าคุณต้องใช้เวลาหลายชั่วโมงในการจัดทำเอกสารคุณลักษณะนี้ จากนั้นอธิบายว่ามันเป็นเพียง 1 ใน 10 ของ 1% (ใช้ตัวเลขจริงตามบรรทัดของรหัสถ้าคุณทำได้พวกเขาอาจจะแย่กว่านี้) ของฐานรหัสจริง เมื่อเขาตระหนักว่าเขาไม่มีเงื่อนงำสิ่งที่การแปลภาษาอังกฤษพูดและมันจะใช้เวลา 20,000 ชั่วโมงในการทำเอกสารระดับนี้เขาจะถอยกลับอย่างรวดเร็ว แต่พยายามอย่างหนักเพื่อให้งานของเขาสำเร็จ อย่าพยายามทำสิ่งนี้ถ้าคุณไม่สามารถดึงมันออกมาและเขาสงสัยว่าคุณกำลังเล่นเขาอยู่

ดูเหมือนว่าผู้สมัครสำหรับแถบDilbert ที่มีผมหงอกเป็นพิเศษในช่วงวันหยุด! คำขอของเขาไม่ฟังดูสมเหตุสมผลในตอนแรก

ลองหัวเราะดูกันว่าเขาต้องการอะไรจริง ๆและทำไมจึงแนะนำให้เขารู้ว่ามันจะต้องเสียเงินเป็นดอลลาร์หรือชั่วโมงเพื่อให้เขาทำสิ่งนั้นและให้เขาตัดสินใจว่าเขาต้องการใช้เงินจำนวนมากกับมันหรือไม่

สำหรับตัวเองให้นับเวลาที่คุณจะต้องทำตามคำขอของเขาที่ดูแปลกประหลาดจากนั้นพิจารณาว่าคุณจะไม่ลงทุนที่ดีกว่าในการหางานใหม่ให้กับนายจ้างที่เต็มใจปฏิบัติต่อคุณ เป็นมืออาชีพ!

นำเขาเข้ามาในสำนักงานของคุณและมอบรหัสทัวร์ให้เขา

เขาจะรู้ว่าเขาทำอะไรที่ไร้สาระและเขาจะเดินออกไปและไม่รบกวนคุณอีกเลย

หากคุณไม่ให้ความต้องการของเขาเพื่อช่วยให้เขาพยายามเข้าใจรหัสของคุณเขาจะพบวิธีที่แตกต่าง แต่ไร้สาระเท่า ๆ กันที่จะกระตุ้นคุณ

นี่เป็นกรณีที่การปลอบใจทำงานได้ดีกว่ารอยขีดข่วน

มันจะดีมากถ้าเรามีนักแปล "ภาษา X เป็นภาษาอังกฤษ" ที่ทำสิ่งนี้ จากนั้นหนึ่งสามารถยิ้มและพูดว่าไม่มีปัญหาเจ้านายคุณจะได้ในเวลาไม่กี่นาที จากนั้นเมลมาพร้อมกับข้อความจำนวนเมกะไบต์ที่อ่าน:

• ให้ a เป็นอาร์เรย์จำนวนเต็มใหม่ที่มี 20 องค์ประกอบ
• ให้ x เป็นตัวแปรในการเก็บจำนวนเต็ม
• ตั้งค่า x เป็น 0
• ในขณะที่ x เล็กกว่า 20 ให้ทำตามที่กำหนดไว้ใน 2 บรรทัดถัดไป
• ตั้งค่าองค์ประกอบอาร์เรย์ของ a ด้วย index x เป็นผลลัพธ์ของการเรียก nThPrime ด้วยอาร์กิวเมนต์ x + 1
• เพิ่ม x 1
• ....

ตัวเลือกอื่นจะแนะนำการเขียนโปรแกรมในเช็คสเปียร์ต่อจากนี้ไป

เจ้านายของฉันต้องการคำอธิบายภาษาอังกฤษแบบบรรทัดต่อบรรทัดของรหัสของเรา

ยาก.

เนื่องจากเขาไม่ได้เป็นโปรแกรมเมอร์เขาจึงไม่สามารถติดตามรหัสได้ดังนั้นจึงต้องการแปลเป็นภาษาอังกฤษทั้งหมด

หากเขาไม่ใช่โปรแกรมเมอร์เขาไม่ควรอ่านรหัส เลย

จัดทำเอกสารระดับสูงแทน

นี่ไม่ใช่คำขอที่สมเหตุสมผลใช่ไหม

เลขที่

ในฐานะโปรแกรมเมอร์คุณมีงานที่ "สอง" จริงๆ

สิ่งแรกคือการสร้างโปรแกรมที่ดี ประการที่สองคือ "ขาย" พวกเขาให้กับลูกค้าภายในและภายนอก บริษัท

คำขอเจ้านายของคุณ "เจ็บ" งานแรกของคุณ ใช้เวลาในการจัดทำเอกสารโปรแกรมของคุณมากขึ้น ในทางกลับกันเขาจริง ๆ แล้วทำให้คุณทำงานหนักในงาน "ที่สอง" ของคุณ

หัวหน้าของคุณกำลังขอให้คุณจัดทำเอกสารโปรแกรมของคุณเป็นภาษาอังกฤษเพื่อผลประโยชน์ของเขาและสันนิษฐานว่าเพื่อประโยชน์ของคนที่เขาต้องจัดการกับภายในและภายนอก บริษัท หากคุณช่วยให้เขาทำงานของเขามันควรจะทำงานเพื่อประโยชน์ของคุณในระยะยาวเมื่อคุณขอฮาร์ดแวร์เพิ่มเติมบุคลากรหรือเงินเพื่อเพิ่ม ท้ายที่สุดเขาขอให้คุณทำงานมากขึ้น

ฉันคิดว่าBDDจะเหมาะกับปัญหานี้แม้ว่ามันจะดูเหมือนว่าโครงการของคุณใกล้เสร็จแล้วดังนั้นจึงยากที่จะนำไปใช้ในตอนนี้ดังนั้นจึงเป็นเหมือนการอ้างอิงในอนาคต

ด้วย BDD กรณีใช้งานจะถูกอธิบายว่าเป็นเอกสารที่มนุษย์สามารถอ่านได้ซึ่งจะถูกแปลเป็นการทดสอบการทำงานอัตโนมัติ

อาจคำขอนี้เป็นเวลาที่ดีที่จะเรียนรู้สิ่งต่าง ๆ เช่นANTLR ใช้ ANTLR ใช้ไวยากรณ์ภาษาของคุณแยกโค้ดทั้งหมดที่คุณมีการสำรวจของคุณASTสร้างคำอธิบายแม่แบบที่ใช้สำหรับทุกโหนดเพื่ออธิบายว่าi++ increase i by 1 using postfix increment operatorนั่นควรจะตลกจริงๆ เจ้านายของคุณอาจต้องการให้มีการรวมเครื่องมือนี้ไว้ในสคริปต์การสร้างดังนั้นทุกครั้งที่คุณทำการเปลี่ยนแปลงใด ๆ เขาจะได้รับอีเมลประมาณ 20 MB เพื่ออธิบายสิ่งที่เวอร์ชันใหม่ทำ

ป.ล. แค่ล้อเล่นเขาเป็นคนงี่เง่า

แม้ว่าฉันจะเห็นด้วยว่านี่เป็นคำขอที่ไม่สมเหตุสมผล แต่เจ้านายของคุณอาจชื่นชมสิ่งที่ชอบออกจากDoccoซึ่งแยกรหัสของคุณและแสดงความคิดเห็นแบบบรรทัดต่อบรรทัดหรือประโยคต่อประโยคออกเป็นสองคอลัมน์ HTML โดยมีรหัสต่อหนึ่ง ด้านข้างและร้อยแก้วที่อื่น ๆ แน่นอนว่าคุณต้องพิมพ์ความคิดเห็นด้วยตัวเอง แต่การนำเสนอค่อนข้างดี IMHO แม้สำหรับผู้อ่านที่ไม่ใช่ด้านเทคนิค ดูตัวอย่างเช่นบรรทัดบรรทัดโดยความเห็นส่วนของโค้ดข้อเขียนสำหรับ Underscore.js มีเวอร์ชัน Python และ shell script เช่นกัน

เป็นไปได้ว่าเจ้านายของคุณไม่ได้รับรู้และข่มขู่ แต่เป็นบุคคลที่สมเหตุสมผล ถ้าเป็นเช่นนั้นการใช้เหตุผลกับเขา / เธออาจทำงาน - บทสนทนาทั่วไปที่คุณสัญญาว่าจะให้ "สิ่งที่เขาต้องการ" เช่น; คู่มือร้อยแก้วถึงสิ่งที่โปรแกรมกำลังทำอยู่

ถ้ามันลงมาที่ "ทางของฉันหรือทางหลวง" ให้ตรวจสอบแก๊สของคุณตอนนี้ดีกว่า

คุณสามารถเขียนแบบทดสอบการยอมรับโดยใช้กรอบการออกแบบที่ขับเคลื่อนด้วยพฤติกรรมเช่นแตงกวา ? นั่นจะไม่อธิบายรหัส มันจะอธิบายสิ่งที่มันทำและในภาษาธรรมชาติ นอกจากนี้ยังมีข้อดีของการใช้งานได้ดังนั้นคุณสามารถมั่นใจได้ว่าเอกสารนั้นเป็นข้อมูลที่ทันสมัยเพราะถ้าไม่เป็นเช่นนั้นผู้ทดสอบจะเป็นสีแดง

ลองชมวิดีโอแนะนำ บางทีมันอาจจะเป็นการเบี่ยงเบนที่ดีในขณะที่คุณหาเจ้านายคนใหม่ ... ;-)

ผู้จัดการของคุณมีความสุขที่เขาไม่เข้าใจในสิ่งที่ผู้คนทำและเขาไม่มีภูมิหลังที่จะเข้าใจผลลัพธ์ที่พวกเขาผลิต

ฉันสงสัยว่าเขาคิดวิธีแก้ปัญหานี้อย่างละเอียดถี่ถ้วนและมันอาจดูสมเหตุสมผลสำหรับเขาในแวบแรก แต่ส่วนใหญ่เป็นเพราะเขาไม่เข้าใจว่ารหัสโปรแกรมคืออะไร

โปรแกรมเมอร์ทุกคนเข้าใจถึงความไร้สาระของคำขอนี้ แต่เราทำเพราะเรารู้อย่างหยั่งรู้ว่าเมื่อคุณได้รับภาษาที่ผ่านมาสิ่งที่เปิดเผยก็คืออัลกอริทึมซึ่งเป็นความลับที่เท่าเทียมกัน

// 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

ปัญหาคือที่นี่ในขณะที่ความคิดเห็นอธิบายว่าแต่ละบรรทัดทำอะไรคุณยังไม่มีความคิดว่าโค้ดทำอะไรจริงๆเว้นแต่คุณจะเข้าใจว่าความหมายทั้งหมดเป็นอย่างไร เห็นได้ชัดว่าคุณเป็นโปรแกรมเมอร์และเคยเห็นรูปแบบนี้มาก่อน แต่แสดงสิ่งนี้กับคนที่เข้าใจการขายเพียงอย่างเดียวและเขาจะสับสนเหมือนเดิมหลังจากอ่านความคิดเห็นอย่างที่เขาเคยเป็นมาก่อน

คุณสามารถประหยัดเวลาได้ด้วยการสอนเจ้านายของคุณเกี่ยวกับการเขียนโปรแกรมพื้นฐาน หากเขาต้องการอ่านรหัสของคุณให้เครื่องมือแก่เขาเพื่อให้สามารถทำเช่นนั้นได้ ภาษาส่วนใหญ่นั้นค่อนข้างมีขนาดกะทัดรัดและฉลาดหลักแหลมและการเรียนรู้โครงสร้างใช้เวลาเพียงหนึ่งหรือสองชั่วโมงเท่านั้น เขาจะยอมแพ้หลังจากนั้นไม่กี่วัน แต่อย่างน้อยเขาก็จะรู้ว่าเขากำลังทำอะไรอยู่และที่สำคัญกว่านั้นคือทำไมเขาถึงไม่ต้องการอ่านโค้ดของคุณ

IMHO ... ถ้าเขารับผิดชอบในการทำงานให้เสร็จเขาควรรู้ว่ามันทำงานอย่างไร ... :)