Mã nhận xét có thể là tài liệu có giá trị?

Tôi đã viết đoạn mã sau:

if (boutique == null) {
    boutique = new Boutique();

    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.persist(boutique);
} else {
    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    //boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.merge(boutique);
}

Có một dòng nhận xét ở đây. Nhưng tôi nghĩ rằng nó làm cho mã rõ ràng hơn, bằng cách làm rõ sự khác biệt giữa ifvà else. Sự khác biệt thậm chí còn đáng chú ý hơn với màu sắc nổi bật.

Có thể bình luận ra mã như thế này bao giờ là một ý tưởng tốt?

Hầu hết các câu trả lời tập trung vào cách cấu trúc lại một trường hợp cụ thể này, nhưng hãy để tôi đưa ra một câu trả lời chung cho lý do tại sao mã nhận xét thường là xấu:

Đầu tiên, nhận xét mã không được biên dịch. Điều này là hiển nhiên, nhưng nó có nghĩa là:

1. Mã thậm chí có thể không hoạt động.

2. Khi sự phụ thuộc của bình luận thay đổi, nó rõ ràng sẽ không bị phá vỡ.

Mã nhận xét là rất nhiều "mã chết". Càng ngồi lâu, nó càng mục nát và cung cấp ngày càng ít giá trị cho nhà phát triển tiếp theo.

Thứ hai, mục đích không rõ ràng. Bạn thực sự cần một bình luận dài hơn cung cấp bối cảnh cho lý do tại sao có những dòng bình luận ngẫu nhiên. Khi tôi chỉ thấy một dòng mã nhận xét, tôi phải nghiên cứu làm thế nào nó đến đó chỉ để hiểu tại sao nó lại đến đó. Ai đã viết nó? Cam kết gì? Thông điệp cam kết / bối cảnh là gì? Etcetera.

Xem xét lựa chọn thay thế:

• Nếu mục tiêu là các ví dụ cung cấp việc sử dụng hàm / api, thì hãy cung cấp một bài kiểm tra đơn vị. Các bài kiểm tra đơn vị là mã thực và sẽ bị hỏng khi không còn đúng nữa.
• Nếu mục đích là để bảo tồn phiên bản mã trước đó, hãy sử dụng kiểm soát nguồn. Tôi muốn kiểm tra một phiên bản trước đó sau đó chuyển các nhận xét trong toàn bộ cơ sở mã để "hoàn nguyên" một thay đổi.
• Nếu mục đích là để duy trì một phiên bản thay thế của cùng một mã, hãy sử dụng kiểm soát nguồn (một lần nữa). Rốt cuộc, đó là những gì các chi nhánh dành cho.
• Nếu mục đích là để làm rõ cấu trúc, hãy xem xét cách bạn có thể cấu trúc lại mã để làm cho nó rõ ràng hơn. Hầu hết các câu trả lời khác là những ví dụ tốt về cách bạn có thể làm điều này.

Vấn đề lớn nhất với mã này là bạn đã sao chép 6 dòng đó. Một khi bạn loại bỏ sự trùng lặp đó, nhận xét đó là vô ích.

Nếu bạn tạo một boutiqueDao.mergeOrPersistphương thức, bạn có thể viết lại thành:

if (boutique == null) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

boutiqueDao.mergeOrPersist(boutique);

Mã hoặc tạo hoặc cập nhật một đối tượng nhất định là phổ biến, vì vậy bạn nên giải quyết nó một lần, ví dụ bằng cách tạo một mergeOrPersistphương thức. Bạn chắc chắn không nên sao chép tất cả các mã gán cho hai trường hợp đó.

Nhiều ORM đã được xây dựng để hỗ trợ cho việc này theo một cách nào đó. Ví dụ, họ có thể tạo một hàng mới nếu idbằng 0 và cập nhật một hàng hiện có nếu idkhông phải là 0. Biểu mẫu chính xác phụ thuộc vào ORM được đề cập và vì tôi không quen thuộc với công nghệ bạn đang sử dụng, tôi không thể giúp bạn điều đó.

Nếu bạn không muốn tạo một mergeOrPersistphương thức, bạn nên loại bỏ sự trùng lặp theo một cách khác, ví dụ bằng cách giới thiệu một isNewBoutiquecờ. Điều đó có thể không đẹp, nhưng nó vẫn tốt hơn nhiều so với việc sao chép toàn bộ logic gán.

bool isNewBoutique = boutique == null;
if (isNewBoutique) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

if (isNewBoutique)
    boutiqueDao.persist(boutique);
else
    boutiqueDao.merge(boutique);

Đây là một ý tưởng hoàn toàn khủng khiếp . Nó không làm rõ ý định là gì. Có phải nhà phát triển đã nhận xét sai lầm? Để kiểm tra cái gì? Chuyện gì đang xảy ra vậy?!

Ngoài thực tế là tôi thấy 6 dòng hoàn toàn bằng nhau trong cả hai trường hợp. Thay vào đó, bạn nên ngăn chặn việc sao chép mã này. Sau đó, sẽ rõ ràng hơn rằng trong một trường hợp, bạn gọi thêm setSelected.

Không, đó là một ý tưởng tồi tệ. Dựa trên đoạn mã đó, những suy nghĩ sau đây xuất hiện trong đầu tôi:

• Dòng này được nhận xét vì nhà phát triển đã gỡ lỗi nó và quên khôi phục dòng về trạng thái cũ
• Dòng này được nhận xét vì nó từng là một phần của logic kinh doanh, nhưng nó không còn là trường hợp nữa
• Dòng này được nhận xét vì nó gây ra vấn đề về hiệu suất trong sản xuất và nhà phát triển muốn xem tác động của hệ thống sản xuất là gì

Sau khi thấy hàng ngàn dòng mã nhận xét, bây giờ tôi đang làm điều hợp lý duy nhất khi tôi thấy nó: Tôi lập tức xóa nó.

Không có lý do hợp lý để kiểm tra mã nhận xét vào một kho lưu trữ.

Ngoài ra, mã của bạn sử dụng rất nhiều sự trùng lặp. Tôi đề nghị bạn tối ưu hóa điều đó cho khả năng đọc của con người càng sớm càng tốt.

Tôi chỉ muốn thêm vào câu trả lời của CodeInChaos, bằng cách chỉ ra rằng bạn có thể cấu trúc lại nó thành các phương thức nhỏ hơn . Chia sẻ chức năng chung theo thành phần để tránh các điều kiện:

function fill(boutique) {    
  boutique.setSite(site);
  boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
  boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
  boutique.setNom(fluxBoutique.getNom());
  boutique.setIdWebSC(fluxBoutique.getId());
  boutique.setDateModification(new Date());
}    

function create() {
  boutique = new Boutique();      
  fill(boutique);
  boutique.setSelected(false);
  return boutiqueDao.persist(boutique);
}

function update(boutique) {
  fill(boutiquie);
  return boutiquieDao.merge(boutique); 
}

function createOrUpdate(boutique) {
  if (boutique == null) {
    return create();
  }
  return update(boutique);  
}

Trong khi đây rõ ràng không phải là một trường hợp tốt cho mã nhận xét, có một tình huống mà tôi nghĩ rằng nó đảm bảo:

// The following code is obvious but does not work because of <x>
// <offending code>
<uglier answer that actually does work>

Đó là một cảnh báo cho bất cứ ai nhìn thấy sau đó rằng sự cải thiện rõ ràng là không.

Chỉnh sửa: Tôi đang nói về một cái gì đó nhỏ. Nếu nó lớn, bạn giải thích thay thế.

Trong ví dụ cụ thể này, tôi thấy mã nhận xét rất mơ hồ, phần lớn là vì những lý do được nêu trong câu trả lời của Dibkke . Những người khác đã đề xuất những cách mà bạn có thể cấu trúc lại mã để tránh ngay cả sự cám dỗ để làm điều này, tuy nhiên, nếu không thể vì một lý do nào đó (ví dụ, các dòng tương tự, nhưng không đủ gần), tôi sẽ đánh giá cao một nhận xét như:

// Không cần bỏ chọn cửa hàng này, vì [WHATEVER]

Tuy nhiên, tôi nghĩ rằng có một số tình huống mà việc để lại (hoặc thậm chí thêm nhận xét) mã không đáng trách. Khi sử dụng một cái gì đó như MATLAB hoặc NumPY, người ta thường có thể viết mã tương đương 1) lặp lại trên một mảng, xử lý một phần tử tại một thời điểm hoặc 2) vận hành toàn bộ mảng cùng một lúc. Trong một số trường hợp, cái sau nhanh hơn nhiều, nhưng cũng khó đọc hơn rất nhiều. Nếu tôi thay thế một số mã bằng mã hóa tương đương, tôi đã nhúng mã gốc vào một nhận xét gần đó, như sau:

%% Mã vector dưới đây thực hiện điều này:

% for ii in 1:N
%    for jj in 1:N
%      etc.

% nhưng phiên bản ma trận chạy nhanh hơn 15 lần so với đầu vào thông thường (MK, 03/10/2013)

Rõ ràng, người ta cần lưu ý rằng hai phiên bản thực sự làm điều tương tự và nhận xét đó sẽ không đồng bộ với mã thực tế hoặc bị xóa nếu mã thay đổi. Rõ ràng, những cảnh báo thông thường về tối ưu hóa sớm cũng được áp dụng ...

Lần duy nhất tôi thấy mã nhận xét hữu ích là trong các tệp cấu hình, trong đó mã cho mọi tùy chọn được cung cấp, nhưng đã nhận xét, giúp dễ dàng bật cài đặt bằng cách chỉ xóa các đánh dấu nhận xét:

## Enable support for mouse input:
# enable_mouse = true

Trong trường hợp này, mã nhận xét giúp ghi lại tất cả các tùy chọn có sẵn và cách sử dụng chúng. Nó cũng là thông thường để sử dụng các giá trị mặc định trong suốt, vì vậy mã cũng đang ghi lại các cài đặt mặc định.

Nói chung, mã chỉ là tài liệu tự viết cho người đã viết mã. Nếu tài liệu được yêu cầu, viết tài liệu. Không thể chấp nhận được việc mong đợi một nhà phát triển mới đối với cơ sở mã nguồn sẽ ngồi đọc hàng ngàn dòng mã để cố gắng tìm hiểu từ cấp cao những gì đang xảy ra.

Trong trường hợp này, mục đích của dòng mã nhận xét là để hiển thị sự khác biệt giữa hai trường hợp mã trùng lặp. Thay vì cố gắng ghi lại sự khác biệt một cách tinh tế bằng một bình luận, hãy viết lại mã để nó có ý nghĩa. Sau đó, nếu bạn vẫn cảm thấy cần phải bình luận về mã, hãy viết một bình luận thích hợp.

Không, mã nhận xét trở nên cũ kỹ và sớm tệ hơn vô giá trị, nó thường có hại, vì nó cắt một số khía cạnh của việc thực hiện, cùng với tất cả các giả định hiện tại.

Nhận xét nên bao gồm chi tiết giao diện và chức năng dự định; "Hàm dự định": có thể bao gồm, đầu tiên chúng ta thử cái này, sau đó chúng ta thử cái kia, sau đó chúng ta thất bại theo cách này.

Các lập trình viên mà tôi đã thấy cố gắng để lại những điều trong các bình luận chỉ là yêu những gì họ đã viết, không muốn mất nó, ngay cả khi nó không thêm bất cứ điều gì vào thành phẩm.

Nó có thể trong những trường hợp rất hiếm, nhưng không phải như bạn đã làm nó. Các câu trả lời khác đã băm khá tốt lý do cho điều đó.

Một trong những trường hợp hiếm hoi là thông số RPM mẫu mà chúng tôi sử dụng trong cửa hàng của tôi làm điểm khởi đầu cho tất cả các gói mới, phần lớn để đảm bảo không có gì quan trọng bị bỏ sót. Hầu hết, nhưng không phải tất cả các gói của chúng tôi đều có tarball chứa các nguồn có tên tiêu chuẩn và được chỉ định bằng thẻ:

Name:           foomatic
Version:        3.14
 ...
Source0:        %{name}-%{version}.tar.gz

Đối với các gói không có nguồn, chúng tôi nhận xét thẻ và đặt một nhận xét khác phía trên nó để duy trì định dạng chuẩn và cho biết ai đó đã dừng lại và nghĩ về vấn đề này như một phần của quá trình phát triển:

Name:           barmatic
Version:        2.71
 ...
# This package has no sources.
# Source0:        %{name}-%{version}.tar.gz

Bạn không thêm mã mà bạn biết sẽ không được sử dụng bởi vì, như những người khác đã trình bày, nó có thể bị nhầm lẫn với thứ gì đó thuộc về nó. Nó có thể. tuy nhiên, rất hữu ích để thêm một nhận xét giải thích lý do tại sao mã người ta có thể mong đợi bị thiếu:

if ( condition ) {
  foo();
  // Under most other circumstances, we would do a bar() here, but
  // we can't because the quux isn't activated yet.  We might call
  // bletch() later to rectify the situation.
  baz();
}

Mã nhận xét không được sử dụng bởi ứng dụng, vì vậy nó cần phải được kèm theo các bình luận tiếp theo nêu rõ lý do tại sao nó không được sử dụng. Nhưng trong bối cảnh đó, có những tình huống mà mã nhận xét có thể hữu ích.

Điều tôi nghĩ đến là một trường hợp bạn giải quyết vấn đề bằng cách sử dụng một cách tiếp cận phổ biến và hấp dẫn, nhưng sau đó hóa ra các yêu cầu của vấn đề thực tế của bạn hơi khác với vấn đề đó. Đặc biệt là nếu các yêu cầu của bạn hóa ra cần nhiều mã hơn, sự cám dỗ để các nhà bảo trì "tối ưu hóa" mã bằng cách sử dụng phương pháp cũ có thể sẽ rất mạnh, nhưng làm như vậy sẽ chỉ khiến lỗi trở lại. Giữ việc thực hiện "sai" xung quanh trong các bình luận sẽ giúp xua tan điều này, bởi vì bạn có thể sử dụng nó để minh họa chính xác tại sao cách tiếp cận đó sai trong tình huống này.

Đây không phải là một tình huống mà tôi có thể tưởng tượng xảy ra rất thường xuyên. Thông thường, nó là đủ để giải thích mọi thứ mà không bao gồm một triển khai "sai" mẫu. Nhưng tôi có thể tưởng tượng một trường hợp không đủ, vì vậy câu hỏi là liệu nó có hữu ích không, vâng, nó có thể. Chỉ là không phải hầu hết thời gian.

Điều này không có vẻ tốt bạn thân.

Mã nhận xét là ... chỉ không phải mã. Mã là để thực hiện logic. Làm cho một mã dễ đọc hơn trong chính nó là một nghệ thuật. Như @CodesInChaos đã đề xuất rằng các dòng mã lặp đi lặp lại không triển khai logic rất tốt .

Bạn có thực sự nghĩ rằng một lập trình viên thực thụ sẽ thích khả năng đọc hơn so với thực hiện logic. (bằng cách chúng tôi có ý kiến ​​và 'bổ sung' để đưa vào biểu diễn logic của chúng tôi).

Theo tôi nghĩ, người ta nên viết một mã cho trình biên dịch và điều đó thật tốt - nếu 'nó' hiểu được mã đó. Đối với khả năng đọc của con người Nhận xét là tốt, cho các nhà phát triển (về lâu dài), cho những người sử dụng lại mã đó (ví dụ: người kiểm tra).

Nếu không, bạn có thể thử một cái gì đó linh hoạt hơn ở đây, một cái gì đó như

boutique.setSite (trang web) có thể được thay thế bằng

setsiteof.b chữ (trang web). Có nhiều khía cạnh và quan điểm khác nhau của OOP thông qua đó bạn có thể tăng khả năng đọc.

Mặc dù mã này ban đầu có vẻ rất hấp dẫn và người ta có thể nghĩ rằng anh ta đã tìm ra cách dễ đọc cho con người trong khi trình biên dịch cũng thực hiện công việc của nó một cách hoàn hảo, và tất cả chúng ta bắt đầu theo cách thực hành này, nó sẽ dẫn đến một tệp mờ sẽ trở nên khó đọc hơn trong thời gian và phức tạp hơn vì nó sẽ mở rộng đường xuống.