Bạn có thêm thông tin vào đầu mỗi tệp .hpp/.cpp không?

Question

Khi tạo tệp tiêu đề/nguồn C++ mới, bạn thêm thông tin nào vào đầu? Ví dụ: bạn có thêm ngày, tên của bạn, mô tả tệp, v.v. không? Bạn có sử dụng định dạng có cấu trúc cho thông tin này không?

ví dụ:

// Foo.cpp - Implementation of the Foo class 
// Date: 2008-25-11 
// Created by: John Smith 

Một đội tôi biết nhúng CVS cam kết thông điệp đến chân của mỗi tập tin, nhưng tôi không chắc là tôi muốn đi xa ...

Answer 1

Thông tin về người đã tạo tệp và thời điểm và ai đã chỉnh sửa tệp đó và khi nào tất cả đều nằm trong kiểm soát nguồn. Nếu nhóm của bạn có thực hành tốt xung quanh nhận xét đăng ký, thì bạn cũng sẽ biết lý do cho từng thay đổi. Không cần bình luận cho những thứ đó.

Tôi nghĩ rằng 100% hợp pháp - khôn ngoan, thậm chí - để đặt khối nhận xét, miễn là cần thiết, giải thích mục đích của lớp/mô-đun. Khi người tiếp theo thay đổi nó, họ sẽ có ý tưởng tốt hơn về tầm nhìn tổng thể và liệu tệp này có phải là nơi thích hợp cho sự thay đổi của họ hay không.

Một số cửa hàng đặt thông báo bản quyền và thư mục pháp lý khác trong nhận xét tệp nguồn. Điều này khiến tôi trở nên ngớ ngẩn - nếu mã nguồn (non-OSS) của bạn đã biến nó thành máy chủ của người khác mà bạn không biết hoặc không cho phép, thông báo bản quyền có lẽ sẽ không ngăn cản họ làm bất cứ điều gì với nó. IANAL, YMMV.

Answer 2

tôi không nhúng ngày bởi vì nó dư thừa. Nếu ai đó muốn biết ngày một tập tin được tạo ra không tin tưởng tác giả, hãy tin tưởng hệ thống kiểm soát nguồn của bạn. Nó phải là câu trả lời defintive cho ngày tạo.

Tôi chắc chắn không chống lại việc nhúng kiểm tra trong thư mặc dù. Đó là khá hữu ích.

Answer 3

Không. Hầu hết các công cụ có thể được lấy ra từ hệ thống versioning khi cần thiết, do đó nó dư thừa để thêm vào. Điều đó sẽ để lại cho bạn mô tả nội dung của tệp nhưng đó là một phần của tài liệu lớp học hầu hết thời gian (hoặc ít nhất là tài liệu về loại cụ thể).

Tôi không làm gì trong số đó, nhưng sau đó một lần nữa, tôi không thích tàu tuần dương.

Answer 4

Tôi bao gồm tên tệp, mô tả ngắn gọn về mục đích của tệp và thẻ $ Id $ cho mục đích CVS hoặc Subversion. Người tạo tệp và ngày tạo có thể được tìm thấy bằng cách kiểm tra kho lưu trữ, vì vậy không cần thiết.

Tên tệp được bao gồm bởi vì tùy thuộc vào những gì bạn đang sử dụng để chỉnh sửa tệp, có thể không hoàn toàn rõ ràng khi bạn chỉnh sửa tệp. Mô tả có thể được sử dụng để xác định xem một chút mã có nằm trong tệp hay không hoặc liệu nó có được chuyển sang tệp khác hay không. Và tất nhiên, $ Id $ cung cấp cho bạn thời gian thay đổi cuối cùng và trình chỉnh sửa cuối cùng.

Việc nhúng thông báo đăng ký chỉ hữu ích khi thư hữu ích và chỉ khi tệp được cập nhật một lần và một lúc. Bao gồm mọi thông báo sẽ chỉ đơn giản là bloat các tập tin đến điểm mà có nhiều ý kiến ​​mô tả thay đổi hơn là có mã thực tế. Tốt nhất để rời khỏi kho lưu trữ đó; thường nó chỉ là một dòng lệnh ngắn để có được nhật ký đăng ký của tập tin.

Nếu bạn bị mắc kẹt với hệ thống kiểm soát sửa đổi không thể giữ lịch sử cho các di chuyển và bản sao, trong trường hợp đó chỉ cần tham khảo tệp gốc và số phiên bản của nó. Tất nhiên, nếu bạn đang sử dụng một hệ thống đã được tạo ra đôi khi trong thế kỷ này và không phải là cuối cùng, đó không phải là một vấn đề.

Answer 5

Chúng tôi bắt buộc phải đặt thông tin bản quyền ở đầu mỗi tệp. Tôi nghĩ rằng ngày tháng, tác giả, và tên của tập tin là một sự lãng phí thời gian.

Chúng tôi cũng có hệ thống append kiểm soát nguồn của chúng tôi check-in ý kiến ​​tại các đáy của mỗi tập tin. Ban đầu tôi ghét nhật ký thay đổi, nhưng theo thời gian tôi đã học cách thích nó. Nó thực sự hữu ích khi hợp nhất các thay đổi.

Answer 6

Nếu bạn đang sử dụng CVS, hãy xem số keyword substitutions. Họ sẽ giúp tự động nhúng thông tin đó.

Cá nhân tôi dính này ở phía trên cùng của tất cả các tập tin nguồn của tôi:

// $Id$ 

bình luận thông tin khác tôi nhúng để được phân tích với Doxygen, nếu chúng liên quan đến một cái gì đó cụ thể (các tập tin, các lớp, một loại, v.v.)

Answer 7

Chúng tôi sử dụng RCS của chúng tôi để tự động đóng dấu sau vào file:

Copyright,

tên RCS tập tin,

ngày sửa đổi,

Tác giả của sự thay đổi cuối cùng,

Số sửa đổi RCS

I nghĩ rằng điều này rất thuận tiện. Tôi thực sự thích có tên tập tin tự động dân cư trong mỗi tập tin, bởi vì nó làm cho việc tìm kiếm các giải pháp cho các tập tin rất nhanh chóng.

Answer 8

tôi thường chỉ thêm bất kỳ "Thông tin bình luận" khi ... tôi không nghĩ rằng tôi sẽ nhớ hay của nó không rõ ràng những gì một cái gì đó đang làm hoặc khi tôi phát hành mã nguồn và tôi thực sự muốn người khác có thể sử dụng/học hỏi từ nó.

Answer 9

Tôi thường bao gồm mô tả về mục đích của mã được tìm thấy trong tệp đó. Mọi thứ khác dường như bị xử lý ở những nơi khác: ngày và ý kiến ​​trong kiểm soát nguồn, vv

Answer 10

Nguyên đã trả lời ở đây, nhưng kể từ khi bị xóa: 134249

tôi sẽ chỉ đưa hai điều:

• cấp phép/quyền tác giả thông tin
• bình luận theo yêu cầu của các công cụ tài liệu-tạo (ví dụ, các ý kiến ​​phải trong tiêu đề để làm việc - nếu không, họ nên đi trong các tập tin định nghĩa)

Bất cứ điều gì khác là lông tơ không cần thiết sẽ không được duy trì, và cuối cùng sẽ trở nên tồi tệ hơn không có gì cả.

Lúc đó tôi làm việc cho một công ty quốc phòng lớn và chúng tôi có các tiêu chuẩn mã hóa của draconian.Nếu bạn theo họ đến bức thư (và hầu hết mọi người không), hầu hết các tiêu đề của bạn sẽ được cấu tạo chủ yếu từ sự vô nghĩa đó. Nghiêm trọng hơn nữa là các fluff giống hệt nhau được yêu cầu phải được đặt trong các tập tin nguồn là tốt, có nghĩa là hai bản sao của fluff được ra khỏi ngày và trở nên gây hiểu nhầm.

Answer 11

Mọi người đều nói rằng điều khiển nguồn của bạn sẽ có thông tin ngày và lập trình viên, nhưng điều đó không phải lúc nào cũng đúng. Tôi đã làm việc trong một cửa hàng đã sử dụng Source Safe, và nó vẫn ổn cho đến khi ai đó quyết định chuyển một tệp đến một vị trí khác. Tại thời điểm đó, về cơ bản nó đã trở thành một tập tin mới theo SS, và không có lịch sử trước đó tồn tại.

Có lẽ vì lý do đó, tên và ngày lập trình viên được tự động thêm vào phần nhận xét ở đầu tệp. Khi có hơn 10 mục, chúng tôi sẽ loại bỏ tất cả các mục trung bình, chỉ để lại ngày và tác giả ban đầu và thông tin hiện tại.

Answer 12

Một tuyên bố bản quyền cho khách hàng của tôi ;-)

Answer 13

Đây là những gì tôi normaly đặt ở đầu file:

///////////// Copyright © 2008 DesuraNET. All rights reserved. ///////////// 
// 
// Project  : [project name] 
// File  : [file name] 
// Description : 
//  [TODO: Write the purpose of ... ] 
// 
// Created On: 11/12/2008 2:24:07 PM 
// Created By: [name] <mailto:[email]> 
//////////////////////////////////////////////////////////////////////////// 

và tôi thiết lập một macro trong vis để làm thêm nó vào và điền thông tin mặc định khi tôi tạo một tệp mới

Answer 14

Chúng tôi sử dụng MSVC & VSS và có plugin bổ sung bất kỳ nhận xét nào bạn chỉ định khi đăng ký vào tệp đang được kiểm tra dưới dạng nhận xét. Nó rất thuận lợi để nhìn vào đầu của tập tin CPP để tìm ra số vé theo dõi lỗi mà một sự thay đổi đã được thực hiện cho.

Answer 15

Tôi đã từng thích đặt từ khóa kiểm soát phiên bản vào tiêu đề của tệp. Nhưng đã phục hồi từ nỗi đau đó. :) Vì hai lý do:

1. Không ai đưa nhận xét vào bất kỳ mục đích sử dụng nào. Bạn luôn luôn nhìn lên những khác biệt được báo cáo bởi hệ thống kiểm soát phiên bản.
2. Nó tạo ra một cơn ác mộng trong việc cố gắng phân biệt các tập lớn vì các từ khóa tạo sự khác biệt là khác biệt duy nhất trong tệp.

Answer 16

Tôi sử dụng Subversion. Đây là những gì tôi muốn đặt gần đầu.

$Id$ 
$HeadURL$ 

Thay thế bản sửa đổi, trình chỉnh sửa cuối cùng, sau đó định vị tệp trong kho. Mặc dù tôi luôn luôn làm việc từ các bản sao làm việc, điều này cho phép tôi in/gửi một tập tin qua email và xem nó sau này để biết chính xác nó đến từ đâu. $HeadURL$ đặc biệt là tốt đẹp bởi vì nó cho biết những gì dự án và chi nhánh các tập tin trong và làm thế nào để có được nó (tốt đẹp với các gói con lồng lớn hơn và như thế).

Đồng ý về sự vô dụng của các khối chú thích thủ công lớn — mặc dù docstrings/Javadocs được đề xuất — và tự động thêm nhật ký cam kết.

Có vẻ như một số bạn đang sử dụng các VCS khủng khiếp, nếu bạn nhận được sự khác biệt hoặc hợp nhất các xung đột do chính các từ khóa tạo ra. Subversion handles it well.