มีจุดที่รวม“ บันทึกการเปลี่ยนแปลง” ในไฟล์รหัสทุกไฟล์เมื่อคุณใช้การควบคุมเวอร์ชันหรือไม่?

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

// 2011-06-14 (John Smith) Change XYZ to ABC to fix Bug #999

และ:

// 2009-95-12 (Bob Jones) Extracted this code to Class Foo 
// <commented-out code here>

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

คุณคิดอย่างไร? คุณใช้ทั้งความคิดเห็นและบันทึกหรือไม่ แค่บันทึก คุณพบว่าการโค้ดง่ายขึ้นเมื่อคุณเห็นโค้ดบล็อกข้างต้นที่ John Smith เปลี่ยนวิธีการตรวจสอบ XYZ เมื่อสัปดาห์ที่แล้วแทนที่จะต้องค้นหาบันทึกและเปรียบเทียบไฟล์โค้ดในเครื่องมือ Diff หรือไม่?

แก้ไข: การใช้ SVN แต่โดยทั่วไปจะเป็นที่เก็บเท่านั้น ไม่มีสาขาไม่มีการรวมไม่มีอะไรนอกจากล็อก + ที่เก็บข้อมูล

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

ดังนั้นจึงไม่น่าแปลกใจที่ฉันจะลบการเปลี่ยนแปลงเหล่านั้นด้วยเหตุผลเดียวกัน

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

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

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

แต่เกรงว่าคุณคิดว่าฉันบอกว่าควรลบความคิดเห็นอย่างสนุกสนานการส่ง WTF รายวันนี้ (จากโค้ดเบสที่ฉันทำงาน) แสดงให้เห็นถึงจุดของฉันอย่างสมบูรณ์แบบ:

/// The GaidenCommand is a specialized Command for use by the
/// CommandManager.
///
/// Note, the word "gaiden" is Japanese and means "side story",
/// see "http://en.wikipedia.org/wiki/Gaiden".
/// Why did I call this "GaidenCommand"? Because it's very similar to
/// a regular Command, but it serves the CommandManager in a different
/// way, and it is not the same as a regular "Command". Also
/// "CommandManagerCommand" is far too long to write. I also toyed with
/// calling this the "AlephCommand", Aleph being a silent Hebrew
/// letter, but Gaiden sounded better.

โอ้ ... เรื่องราวที่ฉันสามารถบอกคุณได้เกี่ยวกับ codebase นั้นและฉันจะยกเว้นว่ามันยังถูกใช้งานโดยองค์กรรัฐบาลที่ใหญ่ที่สุดแห่งหนึ่ง

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

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

ฉันมีไฟล์ ChangeLog ไฟล์เดียวสำหรับแต่ละโครงการที่มีการส่งข้อความยอมรับโดยอัตโนมัติ

เราไม่ได้ฝังความคิดเห็นของ ChangeLog ถ้าเราทำฉันจะลบพวกเขาและมี "พูดคุย" กับคนที่เพิ่มพวกเขา ฉันคิดว่าพวกมันบ่งบอกว่าไม่เข้าใจเครื่องมือที่คุณใช้โดยเฉพาะ vcs

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

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

แต่ฉันรู้อะไร ...

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

ในทางกลับกันร้านค้าของฉันทำสิ่งที่ C # เป็นหลักและเรามักจะใช้ความคิดเห็นแบบอินไลน์ XML เพื่อจัดทำเอกสาร API ของเราดังนั้นการอ่านเอกสารเกี่ยวกับการเปลี่ยนแปลง API สาธารณะจะง่ายขึ้นหรือน้อยลงเช่นเดียวกับการใช้ Intellisense

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

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

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

การควบคุมเวอร์ชันสามารถแทนที่ความคิดเห็นบันทึกการเปลี่ยนแปลงเหล่านั้นในรหัสหาก devs ในทีมของคุณใช้งานถูกต้อง

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

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

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

นี่คือสิ่งที่เหลือจากวันที่บันทึกของ VCS สับสนและระบบ VCS นั้นจัดการได้ยาก (ฉันจำวันเหล่านั้นได้ที่ไหนสักแห่งที่แบ็กเอนด์ของยุค 80)

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

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

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

รหัส PowerBuilder เดิมของเรายังคงใช้มัน แต่ฉันคิดว่านั่นเป็นเพียงปัจจัยความสะดวกสบายสำหรับ peeps บางอย่าง ที่ได้รับการรวบรวมเพื่อเผยแพร่ดังนั้น (IMO พวกเขา oughtta) ใช้ประวัติ VCS ของ friggin

หากคุณใช้ SVN การทำเช่นนี้เป็นการเสียเวลาและไร้ประโยชน์โดยสิ้นเชิง

SVN มีฟังก์ชั่นตำหนิ ที่จะบอกคุณว่าใครทำทุกบรรทัดในไฟล์ที่กำหนดและเมื่อ

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

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

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

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

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

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