Là người đầu tiên nhận xét phân tâm và không chuyên nghiệp?

Tôi chỉ thấy mình viết bình luận sau đây trong một số mã (cổ xưa Visual Basic 6.0) mà tôi đang viết:

If WindowState <> 1 Then
    'The form's not minimized, so we can resize it safely
    '...
End if

Tôi không chắc tại sao tôi vô thức sử dụng "chúng tôi" trong các bình luận của mình. Tôi nghi ngờ đó là vì tôi tưởng tượng ai đó bước qua mã, như thể họ thực sự "làm" tất cả các lệnh trên mỗi dòng, thay vì chỉ xem chúng xảy ra. Với suy nghĩ này, tôi có thể đã sử dụng I can resize it, vì hiện tại tôi đang "làm" nó, hoặc you can resize it, như thể tôi đang nói với bất cứ ai đang "làm" nó trong tương lai, nhưng vì cả hai trường hợp này đều có khả năng xảy ra, tôi sử dụng "chúng tôi" như thể tôi đang dẫn dắt người khác thông qua mã của mình.

Tôi chỉ đơn giản có thể viết lại nó như là it can be resizedvà tránh vấn đề, nhưng nó gây ra sự tò mò của tôi: nó có phổ biến khi sử dụng người đầu tiên như thế này trong các bình luận, hoặc nó được coi là gây mất tập trung và / hoặc không chuyên nghiệp?

Bình luận nên được viết cho con người hiểu. Khi con người giao tiếp, chúng ta thường sử dụng "Tôi", "chúng ta", "bạn", v.v.

Khi ai đó đang cố gắng hiểu một số mã, có hai hoặc nhiều tác nhân: người đọc mã đó và tác giả gốc của mã. Nói "chúng tôi" là tốt. Trừ khi 'chuyên nghiệp', bạn có nghĩa là 'giống như robot'.

Tôi sẽ đề nghị tránh xa việc sử dụng 'Tôi' vì nó tự động chịu mọi trách nhiệm về mã. Nếu những người khác đang đọc nó, nó sẽ trông tệ bởi vì đó có nghĩa là một nỗ lực của nhóm trong trường hợp này. Tôi thờ ơ với việc sử dụng "chúng tôi". Tuy nhiên, nó có thể đi qua như bao gồm cả những độc giả khác một cách vô duyên.

Phiếu bầu của tôi vẫn đi cho ngắn gọn và đồng nhất. Nếu thông điệp có thể được truyền đạt theo cách ít dài dòng hơn, tại sao lại chọn bất cứ điều gì khác? Vì vậy, liên quan đến ví dụ này, tôi sẽ viết:

'The form is not minimized so it can be resized safely.

Tôi thực hiện một trong hai cách tiếp cận, thường là bất cứ điều gì nghe tốt hơn.

Để giải thích những thứ như yêu cầu hoặc biện minh, tôi đi với "chúng tôi" như bạn có ở đó:

// We can't proceed unless the user has given us this information.

Nếu tôi đang giải thích quy trình, tôi có xu hướng sử dụng giọng nói (mệnh lệnh) bắt buộc (sửa tôi nếu đó là thuật ngữ sai):

// Get the foo from bar and make sure it follows our required format.

Cái sau có thể trở nên nguy hiểm khi lặp lại mã, nhưng có những cách sử dụng. Vì vậy, nó không sử dụng tôi hoặc chúng tôi, mà thay vào đó nó thực sự ngụ ý "bạn".

Tôi nghĩ rằng đó chỉ là một biến thể của phong cách viết học thuật / kỹ thuật, thường là không cá nhân. Sử dụng giọng nói thụ động, sử dụng "hoàng gia chúng ta" ("một" là quá cũ).

Theo nguyên tắc chung, nó là không rõ ràng, những người sẽ sử dụng nó anyway - nhận xét là dành cho bảo trì mang lại lợi ích, thường không chỉ dành riêng cho tác giả ban đầu.

Điều đó nói rằng, tôi sử dụng người đầu tiên khá thường xuyên trong các bình luận - để giải thích lý do tại sao tôi đưa ra quyết định cụ thể và những gì tôi đang nghĩ.

Nhận xét sẽ cho bạn biết lý do tại sao một cái gì đó đang được thực hiện, không phải những gì đang được thực hiện. Nếu những gì đang được thực hiện không rõ ràng từ mã, hãy sửa mã, đừng chỉ thêm một nhận xét. Người thứ nhất, người thứ hai, v.v. không quan trọng, vấn đề là truyền đạt thông tin cần thiết.

Nếu bạn phải tường thuật mã, thích các mệnh lệnh, vd

'ensure that the window is not minimized
If WindowState <> 1 Then
    'resize the window
    '...
End if

(Và vui lòng không sử dụng các hằng số trần như "1" trong mã)

Có lẽ chúng ta đang đề cập đến những kẻ nhỏ bé trong chương trình làm nên điều kỳ diệu? :)

Giọng nói thụ động tiếng Anh khó sử dụng và nghe có vẻ tệ. Mọi người thích sử dụng mẫu người (tôi, bạn, chúng tôi, một).

Thí dụ:

(Bạn / chúng tôi / một người phải) sử dụng một đại biểu để chuyển các sự kiện thay đổi kích thước cửa sổ cho phụ huynh

Một đại biểu phải được sử dụng để chuyển các sự kiện thay đổi kích thước cửa sổ cho phụ huynh

Một ví dụ khác (lưu ý rằng bạn thường có thể bỏ qua các mẫu người trong các bình luận):

(Chúng tôi) bắt gặp một ngoại lệ. (Chúng tôi sẽ) hiển thị một hộp thoại lỗi.

Một ngoại lệ đã được bắt và một hộp thoại lỗi sẽ được hiển thị.

Tái bút Thay thế thụ động bằng "bạn" rất phổ biến trong ngôn ngữ tiếng Anh đến nỗi nó cũng đã bắt đầu rò rỉ sang các ngôn ngữ khác. Nghe có vẻ cực kỳ buồn cười, ví dụ, tiếng Phần Lan nơi tồn tại dạng số ít người thứ hai (như tiếng Anh "ngươi").

Nếu bạn đang nói về việc thực hiện chương trình, thì đó không phải là 'chúng tôi', 'bạn' hay 'tôi'. Nhân hóa có thể phổ biến đến mức không thể nhận thấy nhưng đó là một thói quen nguy hiểm (Cảnh báo PDF. Cảnh báo Dijkstra.):

Tôi nghĩ rằng nhân hóa là tồi tệ nhất trong tất cả. Bây giờ tôi đã thấy các chương trình "cố gắng làm mọi thứ", "muốn làm mọi thứ", "tin những điều đó là sự thật", "hiểu biết mọi thứ", v.v. Đừng quá ngây thơ khi tin rằng việc sử dụng ngôn ngữ này là vô hại. Nó mời các lập trình viên xác định chính mình với việc thực hiện chương trình và gần như buộc anh ta sử dụng ngữ nghĩa hoạt động.

Tôi không nghĩ rằng người đầu tiên hoặc "hoàng gia chúng ta" có vẻ không chuyên nghiệp hoặc gây mất tập trung. Tôi nghĩ rằng chúng ta nên nỗ lực viết bình luận bằng tiếng Anh trong E-Prime , tập hợp con của tiếng Anh không có động từ "to be".

Nếu bạn sử dụng quá mức "trở thành" trong các bình luận, bạn sẽ nhận được các câu khó hiểu như:

// X is 10
// X is the user data of the newly-authenticated user
// X is a BigInt

Chà, có thể không phải tất cả cùng một lúc, nhưng sự bình đẳng thực sự có thể khiến những bình luận không rõ ràng.

Tôi nghĩ rằng các yêu cầu viết trong E-Prime giúp làm cho các yêu cầu đó rõ ràng hơn, vì người viết phải chỉ ra một diễn viên cùng với hành động.

Phong cách chính xác để bình luận là người thứ ba không cá nhân; " Biểu mẫu không được thu nhỏ, vì vậy nó có thể được thay đổi kích thước một cách an toàn ".

• Tôi ngây thơ.
• Bạn là người thô bỉ.
• Chúng tôi quá trang trọng (và hoàng gia).

Mỗi câu có thể được viết lại theo cách này (xem ở trên) và đó là cách chuyên nghiệp duy nhất để viết.

Nó phụ thuộc vào nhận xét.

Thông thường, tôi viết bình luận theo cách được đề xuất bởi The mouth of a Cow . Tôi cũng luôn viết các bình luận tạo tài liệu (Doxygen, JavaDoc) theo cách này.

Tuy nhiên, nhiều người thường bỏ qua việc sử dụng kiểm soát phiên bản để xác định ai đã viết / chạm vào các dòng trong tệp nguồn. Đôi khi nói "Tôi" là phù hợp, đặc biệt là khi việc theo dõi "Tôi" trở lại khá dễ dàng với người đã viết mã. Nếu bạn, với tư cách cá nhân, đã đưa ra quyết định, tôi khuyên bạn nên sử dụng "Tôi" (cùng với kiểm soát phiên bản) để xác định và theo dõi các quyết định phù hợp với mã.

Người cha già tốt bụng của tôi (mhrip) sẽ hỏi: "Bạn không có những điều quan trọng hơn để bận tâm chứ?"

Tuy nhiên, cá nhân tôi thích "chúng tôi". Và tôi cũng tự hỏi tại sao tôi viết chúng tôi trong các tài liệu ngược dòng, thậm chí không viết mã, coi tôi là nhân viên duy nhất trong công ty của tôi.

Tuy nhiên, bản thân tôi và tôi đồng ý rằng theo cách này chúng tôi cảm thấy bớt cô đơn :)

Tôi có phải là người duy nhất viết "chúng tôi" và nghĩ "tôi và máy tính" (hay "đội của tôi và máy tính") không? "Chúng tôi" sẽ xử lý yêu cầu bên ngoài đã cho chúng tôi, điều đó có nghĩa là "chúng tôi" cần đọc yêu cầu, mở một số cửa sổ, thực hiện một số tính toán, dựa trên yêu cầu kinh doanh "của chúng tôi". Điều này cũng giúp xem mã là một phần của phía bạn chứ không phải kẻ thù :-)

Đối với các bình luận ngắn, đôi khi tôi viết ở người thứ hai, như thể tôi đang hướng dẫn người khác, gần như là một tin nhắn hướng đến nhà phát triển tiếp theo để đọc bình luận. Nhu la

//You can get a session_id from SYSSession.getSessionID() if you need one

Nhận xét dài hơn (chẳng hạn như tiêu đề hàm dài hoặc một vài dòng mô tả thuật toán) Tôi cố gắng giữ trung lập, không có người thứ nhất, người thứ hai hoặc người thứ ba.

Bạn đã thêm nhận xét này vì mã không đủ rõ ràng. Tôi thường thấy việc thể hiện ý định thông qua các phương pháp được xác định rõ sẽ tránh việc sử dụng các bình luận. Ví dụ, dòng đó có thể đã được chuyển sang một phương thức có tên CanThisFormBeResized.

Một phương thức được đặt tên tốt, tuy nhỏ nhưng đánh bại một nhận xét, bởi vì nó dễ dàng cho các nhận xét và mã không đồng bộ.

Vì vậy, nếu hầu hết các bình luận có thể được thể hiện bằng mã, điều đó để lại rất ít lý do cho các bình luận

• Nếu bình luận của bạn là ý kiến ​​của bạn, thì hãy bắt đầu bằng "Tôi"
• Nếu bạn nghĩ rằng bình luận của bạn nên là một ý kiến ​​được chia sẻ (ví dụ: một thực tiễn tốt nhất), thì hãy bắt đầu với "chúng tôi"
• Nếu bình luận của bạn được hướng vào một số mã tinh ranh được viết bởi một nửa dí dỏm, sau đó loại bỏ nhận xét và đi qua và đấm họ mã nhầm lẫn từ một đồng nghiệp, sau đó giải quyết trực tiếp với họ.

Theo nguyên tắc thông thường, tôi sẽ đề nghị sử dụng ngôi thứ nhất, nghĩa là I.

Tại sao? Không phải vì bản chất chiếm hữu của tôi, mà bởi vì khi mọi người nói ở bất kỳ quan điểm nào khác, họ có xu hướng sử dụng quá nhiều từ hoặc đặt câu quá phức tạp, và bị lạc trong việc cố gắng giải thích mọi thứ. Người đầu tiên có xu hướng luôn dễ đọc nhất.

Cá nhân tôi sẽ viết (bằng C #):

if (WindowState != WindowState.Minimised)
{
     ResizeWindowSafely();
}

Hoặc một cái gì đó dọc theo những dòng đó, do đó không cần bình luận.