Cúc I, Voi, chúng tôi, hoặc cả trong tài liệu mã

41

Tôi thấy mình viết (hy vọng) các bình luận hữu ích trong tài liệu mã (C ++) thuộc loại:

The reason we are doing this is...

Lý do tôi sử dụng "chúng tôi" thay vì "tôi" là vì tôi viết nhiều bài học thuật trong đó "chúng tôi" thường được ưa thích hơn.

Vì vậy, đây là câu hỏi. Có một lý do chính đáng để thích cái này hơn cái kia trong mã tài liệu:

Sử dụng "Chúng tôi": Lý do chúng tôi đang làm điều này là ...
Sử dụng "Tôi": Lý do tôi làm việc này là ...
Sử dụng tên của tôi: Lý do [my name]đã làm điều này là ...
Giọng nói thụ động: Lý do điều này được thực hiện là ...
Không phải: Làm điều này bởi vì ...

Tôi chọn số 1 vì tôi đã quen viết theo cách đó, nhưng tài liệu không dành cho người viết, nó dành cho người đọc, vì vậy tôi tự hỏi liệu việc thêm tên nhà phát triển có hữu ích hay không nếu chỉ thêm một điều nữa cần phải làm được thay đổi khi duy trì mã.

documentation

— Alan Turing
nguồn

Tôi nghĩ rằng đó là tùy thuộc vào sở thích cá nhân. Tôi không thấy bất kỳ lý do nào khiến người ta nói rõ hơn người kia nói chung.

— Điều

6

Làm thế nào về # 5: "Khi trong quá trình các sự kiện của con người ...";)

— waxwing

8

"Bốn điểm và bảy giây trước, tổ tiên của chúng tôi đã học được rằng foo phải bị cấm ít nhất là lực lượng của chúng tôi phải vượt qua với NULL"

— Philip

Liên quan chặt chẽ đến tiếng Anh.SE: Tại sao các lập trình viên luôn sử dụng 'chúng tôi' khi họ thực sự có nghĩa là 'tôi' hoặc 'bạn'? (Thật không may, đã đóng cửa)

— Izkata

2

Tại sao không nói This code was written like this because...? (Giọng nói thụ động)

— Alvin Wong

77

Tôi sẽ đi với:

# 6. Tuyên bố: ...

Thay vì nói "Lý do điều này được thực hiện là vì mỗi Foo phải có một Thanh", chỉ cần nói "Mỗi Foo phải có một Thanh". Làm cho nhận xét thành một tuyên bố chủ động của lý do, chứ không phải là một thụ động. Nhìn chung, phong cách viết tốt hơn, phù hợp hơn với bản chất của mã ( làm gì đó) và the reason this was donecụm từ không thêm thông tin gì. Nó cũng tránh chính xác vấn đề bạn gặp phải.

— Bobson
nguồn

bạn có thể giải thích một chút về lý do tại sao bạn sẽ làm điều đó? Không có lời giải thích, câu trả lời này trông giống như một ý kiến trần trụi, hơi mâu thuẫn với các hướng dẫn sao lưu : '... Ý kiến không tệ lắm, miễn là nó được hỗ trợ với một cái gì đó không phải là vì vì tôi là một chuyên gia. , hay còn gọi là vì tôi đã nói vậy, hay chỉ là vì. Sử dụng kinh nghiệm cụ thể của bạn để sao lưu ý kiến của bạn, như trên, hoặc chỉ ra một số nghiên cứu bạn đã thực hiện trên web hoặc ở nơi khác cung cấp bằng chứng để hỗ trợ cho tuyên bố của bạn ... '

— gnat 15/03/13

15

@gnat "Lý do đã được thực hiện" không thêm bất cứ điều gì vào lời giải thích. Nhận xét nên chứa văn bản vừa đủ để nhận được điểm và không hơn. Để lại các niceties, lời mở đầu và văn bản phụ khác.

— David Harkness 15/03/13

@gnat - Tôi thực sự vừa hoàn thành thêm nhiều hơn khi tôi thấy bình luận của bạn.

— Bobson

1

Tôi nghĩ rằng ví dụ của tôi quá đơn giản, bởi vì thực sự "lý do này đã được thực hiện" không thêm bất cứ điều gì. Nhưng có những trường hợp khi một tình huống khó khăn đòi hỏi một số lời giải thích, và trong trường hợp đó, tôi thấy việc sử dụng "chúng tôi" hoặc "tôi" sẽ tự nhiên hơn, giống như tôi đã sử dụng "Tôi" nhiều lần trong nhận xét này. Nhưng tôi nghĩ rằng câu trả lời của bạn rất rõ ràng về mặt tinh thần: "tuyên bố" gợi ý: sử dụng số lượng từ ít nhất có được điểm rõ ràng.

— Alan Turing

7

Tôi đọc //như becausetrong hầu hết các trường hợp.

— Ilmo Euro

23

Tôi không thích, và thực sự sẽ bỏ hoàn toàn cụm từ giới thiệu đó và chỉ đi đến điểm chính. Tôi cũng cố gắng tránh chỉ nói "điều này" bởi vì nó không có cách nào để biết liệu bình luận có đồng bộ với mã hay không. Nói cách khác, thay vì:

// The reason this was done is to prevent null pointer exceptions later on.

Tôi sẽ nói:

// Frobnicate the widget first so foo can never be null.

Thực tế là bạn đang thêm một bình luận ngụ ý rằng bạn đang nêu rõ lý do, vì vậy bạn không cần phải nói cho mọi người biết bạn đang giải thích lý do. Chỉ cần đưa ra lý do cụ thể nhất có thể, để họ biết rõ nhất có thể cách duy trì mã đó sau này.

— Karl Bielefeldt
nguồn

4

Trong C # (và trong hầu hết các công cụ tài liệu bằng các ngôn ngữ khác) có sự khác biệt giữa tài liệu và bình luận trực tuyến. Ý kiến cá nhân của tôi là bạn nên luôn luôn sử dụng các nhận xét chính thức, theo kiểu khai báo như Bobson và những người khác đề xuất trong tài liệu của một lớp hoặc thành viên, nhưng trong mã, không có gì sai khi kém chính thức hơn. Trong thực tế, đôi khi một nhận xét không chính thức có hiệu quả hơn trong việc giải thích lý do tại sao một cái gì đó được tặng hơn là một giải trình đầy đủ bằng tiếng Anh chính thức.

Đây là một mẫu mà tôi nghĩ minh họa điểm.

/// <summary>
/// Takes data from the remote client and stores it in the database.
/// </summary>
/// <param name="data">The data to store.</param>
public void StoreData(ComplexObject data)
{
    // Don't take candy from strangers
    ComplexObject safeData = SanitizeData(data);
    ...
}

— pswg
nguồn

4

Lưu ý bên: SanitizeDatanên trả lại a SafeComplexObject. ;)

— Jon Purdy

Tôi đồng ý, nhưng tôi thích những bình luận theo nghĩa đen (hơn là ẩn dụ), đặc biệt nếu có thể có những nhà phát triển từ các nền tảng ngôn ngữ khác nhau.

— John B. Lambe

2

Một ý tưởng khác để xem xét sẽ là một bài kiểm tra đơn vị được chế tạo tốt, chứng minh tại sao mã hoạt động theo cách nó thay vì viết một bình luận mô tả. Điều này có một vài lợi ích so với việc viết bình luận:

Nhận xét không phải lúc nào cũng thay đổi khi mã được thay đổi có thể dẫn đến sự nhầm lẫn sau này.
Các bài kiểm tra đơn vị cung cấp cho người bảo trì một cách dễ dàng để chơi với mã. Học một cơ sở mã mới có thể dễ dàng hơn rất nhiều nếu bạn có các đơn vị riêng lẻ mà bạn có thể phá vỡ để quan sát những thay đổi.

Mặc dù con đường này đòi hỏi nhiều công việc hơn, thử nghiệm đơn vị có thể là một hình thức tài liệu tuyệt vời.

— người chết
nguồn

1

Những bình luận tốt rất khó viết, và ngay cả những bình luận tốt nhất cũng thường khó đọc và hiểu. Nếu nhận xét của bạn đủ ngắn gọn để tôi tiếp thu và đủ chính xác để truyền đạt những gì tôi cần biết về mã, thì nó không làm cho tôi bất kỳ sự khác biệt nào về đại từ bạn sử dụng.

Tôi ghét không khuyến khích ai đó bình luận mã của họ vì họ quan tâm đến vụ án, căng thẳng và người của đại từ của họ.

— John M Gant
nguồn

Hãy để tôi làm rõ: đối với các bình luận sẽ trở thành một phần của tài liệu chính thức, một giọng điệu trang trọng hơn là phù hợp, và "tôi" và "chúng tôi" tốt nhất nên tránh. Điều tôi có trong đầu với câu trả lời này là bình luận giải thích không thường xuyên, ví dụ như khi bạn đã làm điều gì đó có vẻ sai đối với chàng trai tiếp theo. Trong những trường hợp đó, nơi chỉ những người làm việc trong cùng một cơ sở mã sẽ nhìn thấy nó, tôi nói làm bất cứ điều gì sẽ truyền đạt ý nghĩa của bạn rõ ràng nhất, ngay cả đó là I wrote the code this way because...hoặc what we really need here is.... Trong những trường hợp đó, một nhận xét rõ ràng quan trọng hơn một phong cách nghiêm ngặt.

— John M Gant

1

Lý do tôi sử dụng "chúng tôi" thay vì "tôi" là vì tôi viết nhiều bài học thuật trong đó "chúng tôi" thường được ưa thích hơn.

Đó là một phong cách xấu, ngay cả đối với các bài báo học thuật, trừ khi bạn đang cố gắng che giấu người thực sự quyết định điểm chính xác đó.

Đối với câu hỏi cụ thể của bạn: Tôi sẽ không để lại nhận xét như vậy, trừ khi bắt đầu bằng:

// TODO: clean this up, ...

hoặc trừ khi nó giải thích một cái gì đó rất quan trọng, điều đó có thể không rõ ràng từ mã. Trong trường hợp đó, hãy bình luận ngắn gọn nhất có thể.

— Bовић
nguồn