ความคิดเห็นของคนแรกเบี่ยงเบนความสนใจและไม่เป็นมืออาชีพหรือไม่

ฉันเพิ่งพบว่าตัวเองกำลังเขียนความคิดเห็นต่อไปนี้ในบางรหัส (archaic Visual Basic 6.0) รหัสที่ฉันเขียน:

If WindowState <> 1 Then
    'The form's not minimized, so we can resize it safely
    '...
End if

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

ฉันสามารถเขียนใหม่เป็นit can be resizedและหลีกเลี่ยงปัญหา แต่มันจุดประกายความอยากรู้ของฉัน: มันเป็นเรื่องธรรมดาที่จะใช้คนแรกเช่นนี้ในการแสดงความคิดเห็นหรือมันถือว่าเป็นการรบกวนและ / หรือไม่เป็นมืออาชีพ?

ความคิดเห็นควรเขียนเพื่อให้มนุษย์เข้าใจ เมื่อมนุษย์สื่อสารเรามักใช้ "ฉัน", "เรา", "คุณ" และอื่น ๆ

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

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

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

'The form is not minimized so it can be resized safely.

ฉันใช้วิธีใดวิธีหนึ่งจากสองวิธีซึ่งโดยปกติแล้วจะเป็นสิ่งที่ดีกว่า

ในการอธิบายสิ่งต่าง ๆ เช่นข้อกำหนดหรือเหตุผลฉันไปกับ "เรา" ตามที่คุณมี:

// We can't proceed unless the user has given us this information.

หากฉันอธิบายกระบวนการฉันมักจะใช้คำสั่งเสียง (คำสั่ง) ที่จำเป็น (แก้ไขฉันหากคำนั้นผิด):

// Get the foo from bar and make sure it follows our required format.

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

ฉันคิดว่ามันเป็นแค่ความแตกต่างของสไตล์การเขียนเชิงวิชาการ / ทางเทคนิคซึ่งมักจะไม่มีตัวตน การใช้เสียงแฝงโดยใช้ "ราชวงศ์เรา" ("หนึ่ง" เป็นวันที่)

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

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

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

หากคุณต้องบรรยายโค้ดให้ชอบสิ่งจำเป็นเช่น

'ensure that the window is not minimized
If WindowState <> 1 Then
    'resize the window
    '...
End if

(และโปรดอย่าใช้ค่าคงที่เปลือยเช่น "1" ในรหัส)

บางทีเราหมายถึงคนตัวเล็ก ๆ ในโปรแกรมทำให้เกิดเวทมนตร์ขึ้นมา? :)

ภาษาอังกฤษแบบพาสซีฟเสียงใช้งานยากและฟังดูแย่ คนชอบใช้แบบฟอร์มบุคคล (ฉันคุณเราหนึ่ง)

ตัวอย่าง:

(คุณ / เรา / หนึ่งคน) ต้องใช้ผู้รับมอบสิทธิ์ในการผ่านหน้าต่างปรับขนาดกิจกรรมให้กับผู้ปกครอง

ผู้รับมอบสิทธิ์จะต้องใช้สำหรับการผ่านหน้าต่างปรับขนาดกิจกรรมเพื่อผู้ปกครอง

ตัวอย่างอื่น (โปรดทราบว่าคุณสามารถละเว้นแบบฟอร์มบุคคลในความคิดเห็น):

(เรา) ตรวจพบข้อยกเว้น (เราจะ) แสดงข้อผิดพลาดโต้ตอบ

พบข้อยกเว้นและไดอะล็อกข้อผิดพลาดจะปรากฏขึ้น

PS การแทนที่แพสซีฟด้วย "คุณ" ถือเป็นเรื่องปกติในภาษาอังกฤษซึ่งเริ่มมีการรั่วไหลเป็นภาษาอื่นเช่นกัน มันฟังดูตลกสุดขีดเช่นภาษาฟินแลนด์ที่มีรูปแบบเอกพจน์บุคคลที่สองอยู่ (เช่นภาษาอังกฤษ "เจ้า")

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

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

ฉันไม่คิดว่าจะเป็นคนแรกหรือ "เราเรา" ดูไม่เป็นมืออาชีพหรือเสียสมาธิ ฉันคิดว่าเราควรพยายามเขียนความคิดเห็นภาษาอังกฤษในE-Primeส่วนย่อยของภาษาอังกฤษที่ไม่มีคำกริยา "เป็น"

หากคุณใช้คำว่า "เป็น" ในความคิดเห็นมากเกินไปคุณจะได้รับข้อความที่สับสนเช่น:

// X is 10
// X is the user data of the newly-authenticated user
// X is a BigInt

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

ฉันคิดว่าข้อกำหนดการเขียนใน E-Prime ช่วยทำให้ข้อกำหนดเหล่านั้นชัดเจนขึ้นเนื่องจากผู้เขียนจะต้องระบุนักแสดงพร้อมกับแอ็คชั่น

สไตล์ที่ถูกต้องสำหรับการแสดงความคิดเห็นคือบุคคลที่สามที่ไม่มีตัวตน; " แบบฟอร์มไม่ย่อเล็กสุดดังนั้นจึงสามารถปรับขนาดได้อย่างปลอดภัย "

• ฉันไร้เดียงสา
• คุณงี่เง่า
• เราเป็นทางการเกินไป (และราช)

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

มันขึ้นอยู่กับความคิดเห็น

โดยปกติผมเขียนแสดงความคิดเห็นในลักษณะที่แนะนำโดยปากของวัว ฉันมักจะเขียนความคิดเห็นที่สร้างเอกสาร (Doxygen, JavaDoc) เสมอในลักษณะนี้

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

คุณพ่อเฒ่าที่ดีของฉันจะถามว่า: "คุณไม่มีสิ่งที่สำคัญกว่าที่จะไปรบกวน"

อย่างไรก็ตามโดยส่วนตัวฉันชอบ "เรา" และฉันก็พบว่าตัวเองสงสัยว่าทำไมฉันถึงเขียนเราในเอกสารอัพสตรีมไม่ใช่รหัสเพราะฉันเป็นพนักงานคนเดียวใน บริษัท ของฉัน

อย่างไรก็ตามฉันเองและฉันเห็นด้วยว่าวิธีนี้เรารู้สึกเหงาน้อยลง :)

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

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

//You can get a session_id from SYSSession.getSessionID() if you need one

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

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

วิธีการที่มีชื่อดี แต่เล็กจะแสดงความคิดเห็นเพราะมันง่ายสำหรับความคิดเห็นและรหัสที่จะไม่ซิงค์

ดังนั้นหากความคิดเห็นส่วนใหญ่สามารถแสดงเป็นรหัสได้นั่นเป็นสาเหตุที่ทำให้มีความคิดเห็นน้อยมาก

• หากความคิดเห็นของคุณเป็นความคิดเห็นของคุณให้เริ่มต้นด้วย "ฉัน"
• หากคุณคิดว่าความคิดเห็นของคุณควรเป็นความเห็นร่วม (เช่นแนวปฏิบัติที่ดีที่สุด) ให้เริ่มด้วย "เรา"
• หากความคิดเห็นของคุณตรงไปที่รหัสหลบซึ่งเขียนโดยครึ่งสติปัญญาแล้วเศษความคิดเห็นและเดินไปและเจาะพวกเขาสับสนรหัสจากเพื่อนร่วมงานแล้วที่อยู่นี้แบบตัวต่อตัวกับพวกเขา

ตามกฎของหัวแม่มือฉันขอแนะนำให้ใช้บุคคลแรก, Iที่อยู่,

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

ส่วนตัวฉันจะเขียน (ใน C #):

if (WindowState != WindowState.Minimised)
{
     ResizeWindowSafely();
}

หรือบางสิ่งบางอย่างตามสายเหล่านั้นจึงไม่ต้องการความคิดเห็น