Đối với các bình luận kiểm soát phiên bản, những người dùng khác làm / đề nghị gì - thì quá khứ hay hiện tại?

I E

• Thay đổi x thành y.
• hoặc là
• Thay đổi x thành y.

Bình luận nên được đọc trong bối cảnh, vì vậy:

Hiện tại

Đối với các nhận xét nguồn trên một phương thức hoặc trước khi một số hành vi xảy ra:

// This function does X
function doX() { ... }

Quá khứ

Đối với ý kiến ​​nguồn sau khi một số hành vi xảy ra

function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ...
}

Và cho các tin nhắn cam kết

chức năng X đã thay đổi

Ví dụ hỗn hợp:

// This function does X
function doX() {
    widget.doY()
    // did Y to widget to prepare it for Z
    ....
}

Quá khứ - Vì bất kỳ ai đọc nó trong tương lai sẽ đề cập đến hành động thay đổi như đã xảy ra trong quá khứ.

Từ ngữ "Thay đổi" ngụ ý rằng bạn hiện đang trong quá trình thực hiện thay đổi và mã có thể chưa kết thúc.

lưu ý: Cá nhân tôi chỉ đưa ra nhận xét thay đổi khi có sự thay đổi mạnh mẽ.

Nhận xét những điều tĩnh, vì vậy họ phải trình bày tình trạng của chương trình như là , và không phải là nó sẽ được. Để trả lời câu hỏi cụ thể của bạn, sẽ phù hợp hơn khi sử dụng thì quá khứ .

Tuy nhiên, loại nhận xét này phù hợp hơn với hệ thống kiểm soát phiên bản của bạn. Kiểm soát phiên bản thực hiện công việc theo dõi thay đổi tốt hơn nhiều so với nhận xét thủ công. Với các hệ thống kiểm soát Phiên bản, sẽ phù hợp hơn khi ghi lại thì hiện tại khi những bình luận đó được áp dụng tại thời điểm thay đổi được cam kết. Nhưng, hoặc sẽ làm việc.

Tôi đặc biệt khuyến nghị rằng các nhận xét duy nhất trong mã của bạn phải là những gì được yêu cầu để hiểu chính mã - mục đích, logic kinh doanh và các trường hợp đặc biệt. Để lại tài liệu thay đổi thiết lập cho hệ thống kiểm soát phiên bản của bạn. Nếu bạn không sử dụng VCS, hãy bắt đầu ngay bây giờ. Có một số VCS chất lượng cao miễn phí (Subversion, Mercurial, Git, v.v.).

Tôi sử dụng thì hiện tại bắt buộc, vì vậy một cái gì đó như:

Thay đổi "x" thành "y"

Điều này được khuyến nghị bởi các nhà phát triển Git:

• cơ thể nên cung cấp một thông điệp cam kết có ý nghĩa, trong đó:
  • sử dụng thì bắt buộc, thì hiện tại: "thay đổi", không "thay đổi" hoặc "thay đổi".

Thoạt nghe có vẻ hơi kỳ quặc, nhưng nếu bạn nghĩ rằng một cam kết là một bản vá làm điều gì đó, nó có ý nghĩa hơn. (Điều này đặc biệt đúng trong một DVCS như Git, nơi bạn lấy các thay đổi từ những người khác hành động trên repo của bạn.)

Nó không thực sự quan trọng; Tôi nghĩ đó là phong cách và sở thích cá nhân. Theo như viết hầu hết mọi thứ, chỉ cần phù hợp với bản thân và với các ý kiến ​​khác.

Mã ý kiến ​​nên được tự nhiên để đọc.

Nếu bạn đang đọc mã nói với chính mình "Mã này đang làm X" thì bạn nên viết nhận xét ở thì hiện tại vì đây có thể là cách mà ai đó đọc mã lúc đó cũng sẽ suy nghĩ. Nếu ở bên kia bạn đã suy nghĩ tại một điểm cụ thể "Mã này đã làm X" thì nó sẽ là thì quá khứ. Cuối cùng, nó thuộc về sở thích cá nhân trừ khi vì một lý do nào đó bạn theo hướng dẫn về cách nhận xét mã của bạn (ví dụ: cho một dự án nhóm hoặc cho một lớp, v.v.).

Nếu bạn đang sử dụng git, quy ước là sử dụng thì hiện tại vì các thông điệp cam kết được tạo bằng các công cụ git (ví dụ: hợp nhất) sử dụng thì hiện tại.

Bạn nên sử dụng thì quá khứ.

Lý do là bạn đang trả lời câu hỏi cam kết này đã đạt được điều gì? Hãy nghĩ về nó như nói với VCS của bạn những gì bạn đã làm:

Cam kết 123
Thay đổi XYZ để làm ABC

Để đưa ra ví dụ ngược lại, sử dụng thì tương lai làm cho nó có vẻ như bạn đang yêu cầu người khác làm điều đó:

Cam kết 123
Thay đổi XYZ để làm ABC

và sử dụng các âm hiện tại giống như bạn đang đi được nửa đường:

Cam kết 123
Thay đổi XYZ để làm ABC

Sử dụng thì hiện tại: "Thay đổi X thành Y", gần như là một mục trong danh sách TODO rõ ràng.

Nói chung, giống như một kịch bản, tránh các động từ như "to" và "is". Ví dụ, đó không phải là "anh ấy đang đi", mà là "anh ấy đi bộ".

Nhưng trong ví dụ cụ thể này-- nếu bạn đang nói về nhận xét mã và không nhận xét đăng ký-- Tôi tin rằng "Thay đổi X thành Y" là một nhận xét khủng khiếp. Nó không thêm thông tin mới và nếu mã được thay đổi, nó thậm chí có thể không chính xác. Sẽ tốt hơn nếu bạn trích xuất mã thành một phương thức (hoặc một lớp) và sau đó ghi lại phương thức đó. Nếu nó đủ rõ ràng thì chỉ cần một tên phương thức tốt là đủ.

Nói về điều này, đối với các phương pháp ghi lại tài liệu, bạn có thể sử dụng thì tương lai, ví dụ: "Nếu số được cung cấp là âm, abssẽ trả về độ lớn của số."

Nhận xét là (hoặc nên), giống như bất cứ điều gì được viết, diễn đạt của một cái gì đó, và chúng chỉ nên tuân theo các quy tắc tương tự trong ngôn ngữ tự nhiên (có tính đến các tốc ký và viết tắt cụ thể cho tình huống hoặc hiện vật được ghi lại.

Nhận xét về thì hiện tại ( .ie "nó thay đổi" hoặc "nó đang thay đổi" ) chỉ ra rằng một phần dữ liệu được vận hành bởi thuật toán tài liệu đang bị ảnh hưởng bằng cách nào đó. Đó là, nó chỉ ra những gì mã đang làm hoặc những gì đang xảy ra với dữ liệu đang bị thao túng.

Nhận xét trong thì quá khứ nên chỉ ra một khẳng định, điều kiện tiên quyết hoặc hậu điều kiện của một cái gì đó đã xảy ra trước thời điểm mà bình luận cư trú. Ví dụ:

Đầu vào đã được xác thực trước khi nhập khối mã này

hoặc là

Dữ liệu đã được ghi vào tệp ở cuối đoạn mã này đang được thực thi

Nhận xét trong thì quá khứ cũng có thể giải thích lý do tại sao một cái gì đó đang được thực hiện ( chức năng này làm X và Y để xử lý một vấn đề với cơ sở dữ liệu cũ. )

Nhận xét trong thì quá khứ chỉ ra một thay đổi đối với chính mã (.ie. X đã được thay đổi thành Y ) không nên tồn tại trong mã. Thay vào đó, chúng nên tồn tại dưới dạng các nhận xét sửa đổi trong kho lưu trữ mã nguồn.

Nhận xét trong tương lai sẽ chỉ ra một điều kiện cần được đáp ứng hoặc giải quyết, nhưng vì lý do X hoặc Y không được thực hiện ngay bây giờ. Ví dụ:

Khi cuối cùng chúng ta di chuyển db, chúng ta sẽ phải thay đổi logic này

hoặc là

TODO: càng sớm càng tốt, xem lại xác thực đầu vào - có thể thất bại đối với loại đầu vào X hoặc Y, có thể yêu cầu những thay đổi lớn không thể thực hiện ngay bây giờ.

Đối với loại bình luận TODO sau này , cần tồn tại một số dạng tài liệu khác để đảm bảo rằng những thay đổi đó thực sự diễn ra. Điều cuối cùng bạn muốn là TODO bị mất trong thời gian và không gian: P

Mang nó với một hạt muối, nhưng điển hình đó là những quy tắc tôi thường tuân theo khi tôi tự nhận xét.

Nhận xét là về việc giao tiếp với con người, vì vậy, trong khi tính nhất quán là quan trọng, thì điều quan trọng là không bị sa lầy vào các nguyên tắc khi chính các nguyên tắc đó có được trong cách giao tiếp tốt. Điều đó nói rằng, tôi sử dụng các tiêu chuẩn giả sau đây:

• Nhận xét mô tả một hành vi mong muốn có dạng câu bắt buộc hiện tại.

  // Calculate the width of the curve at x height.
  

• Sử dụng một bộ từ khóa all-caps để mô tả các chủ đề phổ biến trong mã hóa (và để dễ dàng tìm kiếm):

  // NOTE: <This code was written this way for a reason.>
  // TODO: <This code is incomplete. Finish it.>
  // HACK: <This code was written this way for a reason that you won't like.>
  // FIXME: <This code has a known flaw. Fix it.>