รหัสความเห็นสามารถเป็นเอกสารที่มีค่าได้หรือไม่

ฉันเขียนรหัสต่อไปนี้:

if (boutique == null) {
    boutique = new Boutique();

    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.persist(boutique);
} else {
    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    //boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.merge(boutique);
}

มีบรรทัดแสดงความคิดเห็นที่นี่ แต่ผมคิดว่ามันทำให้รหัสชัดเจนโดยการทำให้เห็นได้ชัดว่าสิ่งที่แตกต่างระหว่างและif elseความแตกต่างนั้นชัดเจนยิ่งขึ้นด้วยการเน้นสี

การใส่ความคิดเห็นโค้ดเช่นนี้เป็นความคิดที่ดีได้หรือไม่

คำตอบส่วนใหญ่มุ่งเน้นไปที่วิธีการปรับโครงสร้างกรณีเฉพาะนี้ แต่ให้ฉันเสนอคำตอบทั่วไปว่าทำไมรหัสความเห็นมักไม่ดี:

ก่อนรหัสความเห็นไม่ได้รวบรวม ชัดเจน แต่หมายความว่า:

1. รหัสอาจใช้งานไม่ได้

2. เมื่อการอ้างอิงของความคิดเห็นเปลี่ยนไปจะไม่ทำให้เกิดการแตกหัก

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

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

พิจารณาทางเลือก:

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

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

หากคุณสร้างboutiqueDao.mergeOrPersistวิธีการคุณสามารถเขียนสิ่งนี้เป็น:

if (boutique == null) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

boutiqueDao.mergeOrPersist(boutique);

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

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

หากคุณไม่ต้องการสร้างmergeOrPersistวิธีการคุณควรกำจัดความซ้ำซ้อนด้วยวิธีอื่นตัวอย่างเช่นการแนะนำการisNewBoutiqueตั้งค่าสถานะ นั่นอาจไม่สวย แต่ก็ยังดีกว่าการทำซ้ำตรรกะการกำหนดทั้งหมด

bool isNewBoutique = boutique == null;
if (isNewBoutique) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

if (isNewBoutique)
    boutiqueDao.persist(boutique);
else
    boutiqueDao.merge(boutique);

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

นอกเหนือจากข้อเท็จจริงที่ว่าฉันเห็น 6 บรรทัดที่เท่ากันทั้งสองกรณี คุณควรป้องกันการทำซ้ำรหัสนี้ จากนั้นจะชัดเจนว่าในบางกรณีคุณจะเรียกใช้ setSelected เพิ่มเติม

ไม่มันเป็นความคิดที่แย่มาก ความคิดต่อไปนี้ขึ้นอยู่กับความคิดของฉันตามรหัสส่วนหนึ่ง

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

หลังจากเห็นโค้ดที่ใส่เครื่องหมายคอมเม้นท์หลายพันบรรทัดตอนนี้ฉันกำลังทำสิ่งที่สมเหตุสมผลเพียงอย่างเดียวเมื่อฉันเห็น: ฉันลบมันทันที

ไม่มีเหตุผลที่สมเหตุสมผลในการเช็กอินโค้ดที่ใส่เครื่องหมายคอมเมนต์ลงในที่เก็บ

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

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

function fill(boutique) {    
  boutique.setSite(site);
  boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
  boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
  boutique.setNom(fluxBoutique.getNom());
  boutique.setIdWebSC(fluxBoutique.getId());
  boutique.setDateModification(new Date());
}    

function create() {
  boutique = new Boutique();      
  fill(boutique);
  boutique.setSelected(false);
  return boutiqueDao.persist(boutique);
}

function update(boutique) {
  fill(boutiquie);
  return boutiquieDao.merge(boutique); 
}

function createOrUpdate(boutique) {
  if (boutique == null) {
    return create();
  }
  return update(boutique);  
}

แม้ว่านี่จะไม่ใช่กรณีที่ดีสำหรับการใส่รหัสความคิดเห็น แต่ก็มีสถานการณ์ที่ฉันคิดว่ารับประกัน:

// The following code is obvious but does not work because of <x>
// <offending code>
<uglier answer that actually does work>

มันเป็นการเตือนผู้ที่เห็นในภายหลังว่าการปรับปรุงที่ชัดเจนไม่ใช่

แก้ไข: ฉันกำลังพูดถึงสิ่งเล็ก ๆ ถ้ามันใหญ่คุณควรอธิบายแทน

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

// ไม่จำเป็นต้องยกเลิกการเลือกบูติกนี้เพราะ [WHATEVER]

อย่างไรก็ตามฉันคิดว่ามีบางสถานการณ์ที่รหัสการออก (หรือแม้แต่การเพิ่มความคิดเห็น) ไม่สามารถเข้าใจได้ เมื่อใช้งานอะไรบางอย่างเช่น MATLAB หรือ NumPY เรามักจะเขียนโค้ดที่เทียบเท่าได้ทั้ง 1) วนซ้ำในอาเรย์การประมวลผลทีละองค์ประกอบหรือ 2) ดำเนินการอาเรย์ทั้งหมดในครั้งเดียว ในบางกรณีหลังเร็วกว่า แต่ก็อ่านยากกว่ามาก หากฉันแทนที่รหัสบางส่วนด้วยการเทียบเท่า vectorized ของฉันฉันฝังรหัสเดิมในความคิดเห็นที่ใกล้เคียงเช่นนี้

%% โค้ด vectorized ด้านล่างทำสิ่งนี้:

% for ii in 1:N
%    for jj in 1:N
%      etc.

% แต่เวอร์ชันเมทริกซ์ทำงานได้เร็วขึ้น ~ 15x สำหรับอินพุตทั่วไป (MK, 03/10/2013)

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

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

## Enable support for mouse input:
# enable_mouse = true

ในกรณีนี้รหัสความคิดเห็นจะช่วยให้เอกสารตัวเลือกทั้งหมดที่มีอยู่และวิธีการใช้งาน นอกจากนี้ยังเป็นเรื่องธรรมดาที่จะใช้ค่าเริ่มต้นตลอดดังนั้นรหัสจึงเป็นเอกสารการตั้งค่าเริ่มต้น

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

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

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

ความคิดเห็นควรรวมถึงรายละเอียดส่วนต่อประสานและฟังก์ชันที่ต้องการ "ตั้งใจฟังก์ชั่น": สามารถรวมก่อนอื่นเราลองจากนั้นเราลองแล้วเราล้มเหลวด้วยวิธีนี้

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

อาจเป็นกรณีที่หายากมาก แต่ไม่ใช่ในแบบที่คุณทำ คำตอบอื่น ๆ ได้ถูกแฮ็กเหตุผลที่ดี

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

Name:           foomatic
Version:        3.14
 ...
Source0:        %{name}-%{version}.tar.gz

สำหรับแพคเกจที่ไม่มีแหล่งที่มาเราจะใส่ความคิดเห็นของแท็กและใส่ความคิดเห็นอื่นไว้ด้านบนเพื่อรักษารูปแบบมาตรฐานและระบุว่ามีคนหยุดและคิดเกี่ยวกับปัญหาซึ่งเป็นส่วนหนึ่งของกระบวนการพัฒนา:

Name:           barmatic
Version:        2.71
 ...
# This package has no sources.
# Source0:        %{name}-%{version}.tar.gz

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

if ( condition ) {
  foo();
  // Under most other circumstances, we would do a bar() here, but
  // we can't because the quux isn't activated yet.  We might call
  // bletch() later to rectify the situation.
  baz();
}

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

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

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

มันดูไม่ดีนัก

รหัสความคิดเห็นคือ ... ไม่ใช่รหัส รหัสสำหรับการใช้งานของตรรกะ การสร้างโค้ดให้อ่านง่ายขึ้นนั้นเป็นศิลปะ ดังที่ @CodesInChaos ได้แนะนำไปแล้วว่าบรรทัดของรหัสซ้ำ ๆ นั้นไม่ได้ใช้ตรรกะได้ดี

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

เท่าที่ฉันกังวลหนึ่งควรเขียนรหัสสำหรับคอมไพเลอร์และที่ดี - ถ้า 'มัน' เข้าใจรหัสนั้น สำหรับความสามารถในการอ่านของมนุษย์ความคิดเห็นนั้นดีสำหรับนักพัฒนา (ในระยะยาว) สำหรับผู้ที่ใช้รหัสนั้นซ้ำ (เช่นผู้ทดสอบ)

ไม่เช่นนั้นคุณสามารถลองทำอะไรที่ยืดหยุ่นกว่าได้ที่นี่

boutique.setSite (ไซต์) สามารถถูกแทนที่ด้วย

setsiteof.boutique (สถานที่เดียวกัน) มีแง่มุมและมุมมองที่แตกต่างกันของ OOP ซึ่งคุณสามารถเพิ่มความสามารถในการอ่านได้

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