2009-07-06 48 views
20

http://java.sun.com/docs/codeconv/html/CodeConventions.doc4.html#286Tại sao '//' kiểu nhận xét nhiều dòng (xấu trong Java)?

Tôi đã đọc phần trên của Công ước mã hóa Java và bắt đầu tự hỏi tại sao nó nói "// bình luận ..... không nên được sử dụng trên nhiều dòng liên tiếp cho văn bản bình luận"

sao chép dán phần có liên quan vào đây để tiện theo dõi:

các // comment delimiter thể bình luận ra một dòng hoàn toàn hoặc chỉ có một phần của dòng. Không được sử dụng trên nhiều dòng liên tiếp cho văn bản nhận xét; tuy nhiên, nó có thể được sử dụng trong nhiều dòng liên tiếp cho nhận xét các phần mã.

Có lý do hợp lý nào cho điều này không?

Trả lời

4

Nó giúp sửa đổi và định dạng các nhận xét dài vô cùng đau đớn.

Hầu hết người chỉnh sửa cung cấp một số loại cơ sở gói để tự động bao bọc văn bản thành các dòng có thể đọc được. Nếu mọi dòng bắt đầu bằng '//', dòng đó sẽ được di chuyển xung quanh, sau đó phải xóa và dòng mới được chèn lại. Tất cả những công việc tẻ nhạt đó đều có thể tránh được bằng cách sử dụng các chú thích '/ * */style.

+3

Trừ khi soạn thảo của bạn cũng tự động tiền tố mỗi dòng bằng '*', đó là đáng ngạc nhiên chung ... –

1

Ngay cả khi nhận xét số lượng lớn mã bằng // đôi khi có thể khá khủng khiếp.

tôi sử dụng Eclipes và mặc dù tôi thực sự tận hưởng những cực nhọc nó sẽ đưa ra chương trình hàng ngày có một số sự kết hợp tính năng có thể cho kết quả kỳ lạ ... ví dụ ..

chọn khối lượng lớn các mã mà đã có chứa một số // multiline nhận xét ra mã, nhấn ctrl-/và bình luận tất cả ra, sau đó làm ctrl-shift-f để định dạng mã của bạn, nếu vì lý do nào đó trình định dạng của bạn thỏa thuận với nhận xét, nó sẽ định dạng lại mã của bạn. Sau đó, chọn lại toàn bộ nội dung và bỏ ghi chú đó bằng ctrl-/again ...

một số tùy chọn định dạng sẽ chỉ xoay quanh mã nhận xét và chuyển tiếp tất cả, khi bạn bỏ ghi chú tất cả các ngắt địa ngục và bạn sẽ có để phân tích cú pháp và định dạng lại theo cách thủ công.

Tôi thừa nhận đây là giai thoại, tôi đã cấu hình lại nhật thực để không thực hiện việc này nữa nhưng tôi cũng hạn chế sử dụng // cho chú thích mã lớn như vậy trong lợi ích của/* * /. Tuy nhiên, có nhiều tùy chọn khác tốt hơn để sử dụng:

/** để nhận xét Javadoc */theo cách này, nhận xét có thể truy cập được trong mã hoàn chỉnh, tài liệu, v.v ... bình luận một lần, sử dụng ở mọi nơi.

Nếu bạn biết bạn sẽ tạo nhận xét nhiều dòng không phải là tài liệu java, hãy bắt đầu bằng/* IDE sẽ xử lý phần còn lại theo định dạng. Vì vậy, để giải thích các thuật toán kỳ lạ của vá trong mã tôi sẽ sử dụng/* */chứ không phải là //. Tôi giữ nó cho lót đơn khi cần thiết.

My 2 cent

0

Tôi đã luôn luôn nghĩ rằng/* */phong cách bình luận đã được yêu cầu cho nhiều dòng bình luận vì // được phép "trong nhiều dòng liên tục cho ý kiến ​​ra các phần của mã." Công cụ định dạng mã cần có khả năng phân biệt dễ dàng nhận xét nhiều dòng từ mã nhận xét.

Nếu bạn yêu cầu một công cụ định dạng mã (hoặc IDE) để dọn dẹp tệp của mình, bạn có thể muốn nó bọc lại các chú thích nhiều dòng vào lề, bao quanh các khoảng trắng. Bạn sẽ không phải là công cụ để bọc nhận xét ra mã theo cách này.

Điều đó tất cả đã nói, nhiều quy tắc kiểu ít nhất hơi tùy ý, vì vậy có thể không có lý do chính đáng tại sao Quy ước mã cho Ngôn ngữ lập trình Java được chỉ định/* /nhận xét kiểu là bắt buộc đối với nhận xét nhiều dòng. Thay vào đó, họ có thể quyết định sử dụng/ */nhận xét kiểu chỉ để nhận xét ra mã và sử dụng // nhận xét kiểu cho nhận xét đơn và nhiều dòng.

11

Ý tưởng là nhận xét văn bản nhiều dòng là một thực thể - mà bạn muốn hợp lý giữ lại với nhau. Ngắt dòng trong một nhận xét như vậy không có gì khác hơn là nơi để bọc văn bản, do đó, chia nhỏ nó thành nhiều ý kiến ​​"riêng biệt" không có ý nghĩa. Vì vậy, bạn xây dựng một khối nhận xét duy nhất xung quanh toàn bộ điều - bằng cách sử dụng/* * /.

Để nhận xét ra mã, mỗi dòng là đơn vị lôgic của riêng nó, vì vậy việc sử dụng "//" s liên tiếp là ok - đôi khi. Điều này đặc biệt đúng nếu các dòng riêng lẻ có thể được bình luận trở lại "trong" vì một lý do nào đó, nhưng không phải tất cả chúng. Mặc dù nếu bạn muốn bình luận ra một mã khối toàn bộ nơi nó sẽ không bao giờ có ý nghĩa một phần nhận xét nó vào/ra, bạn vẫn có thể thích sử dụng/* */- một lần nữa để nhóm mọi thứ lại với nhau một cách hợp lý và trực quan.

+2

1 lập luận Semantic. – Stobor

0

Tôi sẽ nói rằng tôi sẽ không gọi nó là "xấu". Thực sự, đó là một vấn đề của công ước, đó là những gì người khác đã nói. Không có gì là xấu về nó, ngoại trừ việc nó có thể làm cho ý kiến ​​nhiều dòng một chút bực bội (keystrokes-khôn ngoan) để làm việc với.

Thành thật mà nói, tôi nghĩ đó là tiêu chuẩn kép với javadoc. Javadoc yêu cầu:

/** 
* Validates a chess move. Use {@link #doMove(int, int, int, int)} to move a piece. 
* 
* @param theFromFile file from which a piece is being moved 
* @param theFromRank rank from which a piece is being moved 
* @param theToFile file to which a piece is being moved 
* @param theToRank rank to which a piece is being moved 
* @return   true if the chess move is valid, otherwise false 
*/ 

và tôi không hiểu tại sao lặp đi lặp lại "*" là bất kỳ tốt hơn so với "//". Vì vậy, với tôi, không có gì vốn có về // là xấu (bởi vì các biên tập viên có thể được thiết lập để tự động thêm chúng vào các bình luận nhiều dòng) và chỉ là quy ước và thông lệ chung.

39

Thực ra, tôi đã sử dụng // cho nhiều dòng trong nhiều năm và không bao giờ gặp phải bất kỳ vấn đề nghiêm trọng nào với nó. Tôi không phải là một fan hâm mộ lớn của số /*...*/ nữa bởi vì bạn nhận được:

/* I'm commenting out all this code for a moment 
    ... 
    /* And here is a multi line comment 
    that was hidden in the middle */ 
    ... 
*/ 

Cảm ơn trình biên dịch sẽ rất khó chịu và cho tôi biết sự cố.

Trong trường hợp như:

... 
// And here is a multi line comment 
// that was hidden in the middle 
... 

trở với một macro duy nhất:

// ... 
// // And here is a multi line comment 
// // that was hidden in the middle 
// ... 

và được hạnh phúc đảo ngược với một vĩ mô duy nhất trả nó trở lại dạng ban đầu

và như đối với :

// but now you have 
    // trouble edditing 
    // your comments so 
    // that every line 
    // is of equal size 

tôi nói:

// Tough, this is a piece of code not a 
    // published novel 
    // and if varying lengths 
    // make 
    // it hard for you to read then heaven 
    // forbid how you handle the code 

Và bạn không chỉ cần ghét edditing:

/****************************************************************** 
* Program: Foo.java            * 
****************************************************************** 
* Author: Codey Art Work          * 
* Purpose: To do something with something and get something not * 
*   forgetting something else.       * 
****************************************************************** 
* Revision History:            * 
****************************************************************** 
* Date | Author |            * 
*--------|--------|----------------------------------------------* 
* 1/2/09 | Jack | Now I have to keep all my comments in this * 
*  |  | tiny little space and if I edit it I just go * 
*  |  | aaarrrrrrggggggggggghhhhhhhhhhh!!!!!!!!!!!!! * 
******************************************************************/ 

mà dường như luôn xuất hiện ở những nơi nhấn mạnh vào /* */ qua //

và tôi muốn chỉ muốn nói với những kẻ ngăn xếp Stack, đây thực sự là một trình soạn thảo tuyệt vời. Làm mẫu mã là dễ dàng như vậy.

+12

+1 sự đồng cảm cho các khối bình luận bên trong các khối bình luận ... – LiraNuna

+0

Tôi đồng ý. Tôi đã từng sử dụng các chú thích đa dòng bằng cách sử dụng/* */nhưng đã rất khó chịu khi lồng ghép chúng vì vậy bây giờ tôi chỉ sử dụng // cho các bình luận mã nội tuyến. Tôi vẫn sử dụng/** */cho tài liệu chức năng mặc dù. –

+3

/** rất tốt cho việc thêm nhận xét doc */ // tốt hơn để nhận xét mã –

0

có thể dành cho công cụ định dạng mã ... nếu bạn đã định dạng tự động (thụt đầu dòng), mã sẽ trông xấu.

trong một số trình chỉnh sửa văn bản, nhận xét sử dụng /** ... **/ có thể được gập lại để nó dễ đọc mã hơn.

0

Theo kinh nghiệm của tôi, các kiểu nhận xét sau đây minh họa tại sao tôi đồng ý với Quy ước về mã Java.

tài liệu Javadoc

/** 
* Description 
* @param foo refers to ... 
* @return true if... 
*/ 

tiếng Anh bình luận

/* 
* The sole reason for this unorthodox construct is just 
* to ... 
*/ 
synchronized(lockObject) { 
    foo = bar; 
} 

hoặc

/* This is a single line comment */ 

Bình luận ra mã (Tôi không muốn kiểm tra trong chú thích code).

// /* Accumulate the results */ 
// for (int i = 0; i < 10; i+=1) { 
//  bar += result[i]; 
// } 

Tại sao?

Tôi thích sử dụng chiều rộng tối đa trong các tệp mã của mình. Eclipse thực hiện một công việc tốt đẹp trong việc phản hồi/* */block các bình luận để biện minh cho bạn với các thiết lập chiều rộng dòng bình luận. Tôi thích hành vi này đối với văn bản viết bằng tiếng Anh. Nhận xét được cập nhật thường xuyên và nếu không bạn sẽ có:

// This is a 
    // long broken up comment that has been edited multiple 
    // times 
    // and the developer was too lazy to fix the justification 

hoặc bạn phải khắc phục sự biện minh đó theo cách thủ công.

Bạn không muốn Eclipse để reflow nhận xét ra mã để sử dụng //

Thứ hai, bạn có thể đánh dấu một khối mã và thêm và loại bỏ // comments phong cách khi bắt đầu mỗi dòng.

Lưu ý, tôi luôn bắt đầu mọi dòng của nhận xét khối bằng dấu *.Sau đây chỉ là chuốc lấy phiền:

/* Accumulate the results */ 
/* 
for (int i = 0; i < 10; i+=1) { 
    /* comment broke the outer comment : Sigh! */ 
    bar += result[i]; 
} 
*/ 
Các vấn đề liên quan