Comment (lập trình máy tính)

Minh họa mã nguồn Java với comment mở đầu được biểu thị bằng màu đỏ và comment nội dòng bằng màu lục. Mã chương trình là bằng màu lam.

Trong lập trình máy tính, comment là phần giải thích, chú thích hay chú giải mà lập trình viên có thể đọc được trong mã nguồn của một chương trình máy tính. Chúng được thêm vào với mục đích là làm cho mã nguồn dễ hiểu hơn cho con người, và nói chung trình biên dịch và trình thông dịch đều bỏ qua chúng. Cú pháp của comment trong nhiều loại ngôn ngữ lập trình thì đều có sự khác nhau rõ rệt.

Comment đôi khi được xử lý bằng nhiều cách khác nhau để tạo sinh tài liệu ra bên ngoài bản thân mã nguồn bằng các trình tạo sinh tài liệu, hoặc được sử dụng cho việc tích hợp với hệ quản lý mã nguồn và các loại công cụ lập trình bên ngoài khác.

Do có tính linh hoạt nên comment có thể được sử dụng theo nhiều lối đa dạng khác nhau, nhưng thường thì các hướng dẫn phong cách lập trình lại có những quy ước chính quy riêng cho comment.

Tổng quan

Comment hay được định dạng thành comment khối (còn được gọi là comment mở đầu hay comment luồng) hoặc được định dạng thành comment dòng (còn được gọi là comment nội dòng).

Comment khối thì phân định một vùng mã nguồn có thể trải ra nhiều dòng, hoặc là phân định một phần của một dòng đơn. Vùng này được chỉ định bằng một dấu định giới bắt đầu và một dấu định giới kết thúc. Một số ngôn ngữ lập trình (như MATLAB) cho chép comment khối được lồng đệ quy vào trong các comment khối khác, nhưng những ngôn ngữ khác (như Java) thì lại không.

Comment dòng thì bắt đầu bằng một dấu định giới comment và tiếp tục cho đến hết dòng, hoặc trong một số tình huống thì bắt đầu tại một cột nhất định (dịch sâu vào trong dòng ký tự) trong mã nguồn, và tiếp tục cho đến hết dòng.

Một số ngôn ngữ lập trình thì sử dụng cả hai loại comment khối và dòng với các dấu định giới comment lần lượt tương ứng khác nhau. Ví dụ, C++ có comment khối được định giới bởi /* và */ và nó có thể trải ra nhiều dòng, còn comment dòng thì được định giới bởi //. Những ngôn ngữ khác thì chỉ hỗ trợ một loại comment. Ví dụ, comment trong Ada và Lua đều là comment dòng: chúng bắt đầu bằng -- và tiếp tục cho đến hết dòng.

Sử dụng

Vận dụng comment như thế nào cho tốt nhất là đề tài còn phải bàn cãi; những người viết comment khác nhau thì đã đưa ra những quan điểm khác nhau và đôi khi trái chiều nhau. Có nhiều cách khác nhau để viết comment và nhiều người viết comment đều đưa ra những đề xuất mâu thuẫn nhau.

Dự trù và đánh giá

Comment có thể được dùng làm một dạng mã giả để phác thảo nên ý định trước khi viết ra code thực tế. Trong trường hợp này, comment nên giải thích cái logic đằng sau code thay vì để chính bản thân cái code giải thích.

/* vòng lặp đi ngược qua tất cả các phần tử do server trả về
(chúng sẽ được xử lý theo thứ tự xảy ra) */
for (i = (numElementsReturned - 1); i >= 0; i--) {
    /* xử lý mỗi dữ liệu của phần tử */
    updatePattern(i, returnedElements[i]);
}

Code mà dễ hiểu thì chưa chắc là nó sẽ hoạt động đúng như nhìn nhận trực quan bên ngoài của người đọc code. Vì vậy loại comment này khá hữu ích để giảm nhẹ gánh nặng của việc đánh giá code, giúp cho người đánh giá code hiểu đúng cách hoạt động thực sự của code.

Mô tả code

Có thể dùng comment để tóm tắt code hoặc để giải thích cái ý định của lập trình viên. Dựa theo trường phái quan niệm này, việc diễn đạt lại cả code bằng văn xuôi bị coi là điều không cần thiết; nếu lại xuất hiện nhu cầu phải giải thích lại code thì đó chính là dấu hiệu cho thấy code quá phức tạp, hoặc do đặt tên tệ, và code nên được viết lại.

"Don't document bad code – rewrite it."
(Code tệ thì viết lại chứ đừng chú giải cho nó.)

"Good comments don't repeat the code or explain it. They clarify its intent. Comments should explain, at a higher level of abstraction than the code, what you're trying to do."
(Comment tốt là comment không lặp lại code hoặc giải thích lại code, comment tốt là comment làm rõ ý định của code. Comment nên giải thích ra những gì mà mình đang muốn làm ở một mức độ trừu tượng cao hơn bản thân cái code đấy.)

Comment cũng có thể được dùng để giải thích lý do vì sao một khối code nào đó lại trông không hợp quy ước hoặc không hợp cách làm tốt nhất. Trong những project có thời gian phát triển rất ngắn, hoặc trong việc sửa bug, thì điều này cực kỳ đúng. Ví dụ:

' Second variable dim because of server errors produced when reuse form data. No
' documentation available on server behavior issue, so just coding around it.
vtx = server.mappath("local settings")

Mô tả thuật toán

Đôi khi mã nguồn có chứa giải pháp mới mẻ hoặc đáng lưu ý cho vấn đề đặc thù. Trong những trường hợp như vậy, comment có thể chứa phần giải thích về phương pháp đó. Những giải thích như vậy có thể chứa các biểu đồ với các chứng minh toán học hình thức. Việc này làm nên phần giải thích cho code chứ không phải để làm rõ cho ý định của code, những ai có tác vụ bảo trì codebase thì comment giải thích như vậy có thể lại cực kỳ hữu ích. Có lẽ đặc biệt đúng nhất trong trường hợp ở những lĩnh vực có vấn đề mang tính đặc thù cao; hay những phép tối ưu hóa, những kiến tạo hoặc những lời gọi hàm hiếm khi được dùng.

Ví dụ, lập trình viên có thể thêm comment để giải thích tại sao lại lựa chọn sắp xếp chèn thay vì chọn quicksort mặc dù sắp xếp chèn về lý thuyết là chậm hơn. Comment có thể được viết như sau:

 list = [f (b), f (b), f (c), f (d), f (a), ...];
 // Chỗ này cần thuật toán 'sắp xếp ổn định', code chạy chậm cũng không sao.
 insertion_sort (list);

Bao chứa tài nguyên

Người ta có thể chèn logo, biểu đồ, lưu đồ với cấu trúc tranh ASCII vào mã nguồn theo định dạng comment. Hơn nữa, người ta còn có thể đính yết thị bản quyền vào làm comment bên trong mã nguồn. Dữ liệu nhị phân cũng có thể được biên mã thành dạng văn bản vào trong comment qua một quá trình gọi là biên mã nhị phân sang văn bản, có điều lối làm như vậy thì không phổ biến và thường hay được chuyển ra file tài nguyên bên ngoài hơn.

Đoạn code sau đây là một biểu đồ ASCII đơn giản miêu tả quy trình xử lý cho một script quản trị hệ thống được chứa trong một Windows Script File chạy dưới Windows Script Host. Mặc dù được định dạng trông như comment, phần biểu đồ đây thực ra là nằm trong phần CDATA của XML, phần này về mặc kĩ thuật thì không phải là comment, nhưng có thể dùng cho mục đích tương tự.

<!-- begin: wsf_resource_nodes -->
<resource id="ProcessDiagram000">
<![CDATA[
 HostApp (Main_process)
    |
    V
script.wsf (app_cmd) --> ClientApp (async_run, batch_process)
                |
                |
                V
         mru.ini (mru_history)  
]]>
</resource>

Mặc dù có thể dễ dàng viết một biểu đồ giống hệt vậy ở dạng comment chuẩn của XML, thì ví dụ đây vẫn minh họa một trường hợp mà lập trình viên có thể chọn hướng không sử dụng comment làm phương pháp bao chứa tài nguyên trong mã nguồn.

Metadata

Bài chi tiết: Metadata

Comment trong chương trình máy tính thường hay chứa đựng metadata về file chương trình.

Một ví dụ là nhiều bảo trì viên phần mềm đặt 'hướng dẫn đệ trình' vào trong comment để cho những ai có cải thiện gì đó thì họ có thể đọc để biết đường gửi về lại cho bảo trì viên.

Các metadata khác thì bao gồm:

• tên của người tạo ra phiên bản gốc của file chương trình cùng với ngày giờ khi phiên bản đầu tiên được tạo ra;
• tên của bảo trì viên hiện thời của chương trình;
• tên của những người khác cũng đã sửa đổi file chương trình trước giờ;
• URL dẫn đến tài liệu bàn về cách sử dụng chương trình;
• tên của giấy phép phần mềm cho file chương trình;
• vân vân.

Khi thuật toán trong một số đoạn của chương trình được dựa trên mô tả trong sách hay nguồn tham khảo khác, thì comment có thể được dùng để cho biết số trang và tựa đề của cuốn sách hay nguồn tham khảo đấy.

Debug

Một lối làm thường thấy của phát triển viên đó là comment out một mẩu code, có nghĩa là thêm cú pháp comment để khiến cho khối code đấy trở thành comment, làm vậy thì mẩu code đó sẽ không bị thực thi trong chương trình cuối. Người ta có thể làm vậy để loại phần code nhất định ra khỏi chương trình cuối mà vẫn giữ đoạn code đó, hoặc (hay thấy hơn) là làm vậy để tìm ra nguyên nhân lỗi trong phần mềm. Bằng cách comment out và chạy từng phần của chương trình một cách có hệ thống thì có thể xác định được nguyên nhân gây lỗi và giúp cho việc sửa chữa.

Sau đây là ví dụ cho việc comment out để loại bỏ code:

 if (opt.equals ("e"))
   opt_enabled = true;

 /*
 if (opt.equals ("d"))
   opt_debug = true;
 */

 if (opt.equals ("v"))
    opt_verbose = true;

Đoạn code bên trên đây cho thấy rằng lập trình viên đã quyết định vô hiệu tùy chọn debug vì một số lý do nào đó.

Nhiều IDE cho phép thêm nhanh hoặc gỡ nhanh các comment như vậy bằng tùy chọn menu đơn hoặc tổ hợp phím. Lập trình viên chỉ cần đánh dấu phần văn bản mà người ta muốn comment hoặc khử-comment rồi lựa chọn tùy chọn thích hợp.

Tự động tạo sinh tài liệu

Bài chi tiết: Trình tạo sinh tài liệu

Các công cụ lập trình đôi khi lưu trữ tài liệu và metadata vào trong comment. Ví dụ như chèn vị trí để tự động bao kèm tập tin header, chèn lệnh để thiết đặt chế độ tô màu cú pháp cho tập tin, hay lưu trữ 'số hiệu bản chỉnh sửa' của tập tin. Những comment điều khiển chức năng đấy còn hay được gọi là chú thích. Việc kèm tài liệu ngay bên trong comment của mã nguồn thì được coi là một cách để đơn giản hóa quá trình tạo tài liệu, cũng như đảm bảo phần tài liệu sẽ luôn được cập nhận đồng bộ với thay đổi trong code.

Ví dụ trình tạo sinh tài liệu thì bao gồm những chương trình như Javadoc để dùng cho Java; Ddoc cho D Doxygen cho C, C++, Java, IDL Visual Expert cho PL/SQL, Transact-SQL, PowerBuilder và PHPDoc cho PHP. Python, Lisp, Elixir, và Clojure thì còn hỗ trợ các dạng docstring nữa.

C#, F# với Visual Basic .NET thực hiện một tính năng tương tự được gọi là "XML Comments", IntelliSense sử dụng những comment đó để tạo sinh tài liệu hướng dẫn cho từng lớp, từng phương thức, v.v. nhằm gợi ý cú pháp cho lập trình viên.

Mở rộng cú pháp

Có những thành phần cú pháp vốn dĩ chỉ được trù định làm comment bình thường thì thỉnh thoảng còn được tái mục đích để truyền tải thông tin bổ sung cho chương trình, chẳng hạn như "comment điều kiện". Những "comment nóng" kiểu như vậy cho dù bị nhiều người coi là giải pháp tạm bợ nhưng đôi khi lại chính là giải pháp thiết thực duy nhất để duy trì tính tương thích ngược.

Chỉ thị

Có trường hợp các ký tự comment bình thường thì được tận dụng để tạo ra chỉ thị đặc biệt dành cho trình soạn thảo hoặc trình biên dịch.

Hai ví dụ comment chỉ thị cho trình thông dịch là:

• Tổ hợp ký tự "shebang" của Unix – #! – dùng ở dòng đầu tiên của script để chỉ định trình thông dịch nào được sử dụng.
• "Comment phép" để nhận biết encoding mà file mã nguồn đang sử dụng.

Dưới đây là script dành cho hệ thống kiểu Unix minh họa cho cả hai ví dụ vừa nêu:

#!/usr/bin/env python3
# -*- coding: UTF-8 -*-
print("Testing")

Kiểu sử dụng comment dưới đây cũng tương tự như vậy, dùng trong C để báo cho trình biên dịch rằng cơ chế "fallthrough" được dùng trong câu lệnh case ở đây là do chủ ý của lập trình viên mà làm chứ không phải do sơ suất:

switch (command) {
    case CMD_SHOW_HELP_AND_EXIT:
      do_show_help();
      /* Fall thru */
    case CMD_EXIT:
      do_exit();
      break;
    case CMD_OTHER:
      do_other();
      break;
    /* ... etc. ... */
  }

Việc chèn comment /* Fall thru */ thế này để ra hiệu cho người đọc thì đã là quy ước chung hồi giờ, nhưng vào năm 2017, trình biên dịch gcc bắt đầu nhìn đến những comment này (và những comment khác dùng để ra dấu là lập trình viên chủ ý), và nếu không tìm thấy, thì sẽ thông báo: "warning: this statement may fall through" (cảnh báo: lệnh này có thể "rớt xuyên").

Many editors and IDEs will read specially formatted comments. For example, the "modeline" feature of Vim; which would change its handling of tabs while editing a source with this comment included near the top of the file:

Nhiều trình soạn thảo và IDE cũng đọc những comment có định dạng đặc biệt thế này. Ví dụ, tính năng "modeline" của Vim, dùng để thay đổi cách xử trí phím tab khi chỉnh sửa file mã nguồn mà có đính comment như thế này ở phần đầu của file:

# vim: tabstop=8 expandtab shiftwidth=4 softtabstop=4

Xoa dịu stress

Đôi khi lập trình viên sẽ thêm comment như là một cách giải tỏa stress bằng cách bình luận về các công cụ phát triển, các đổi thủ cạnh tranh, chủ lao động, điều kiện làm việc, hoặc về chính chất lượng của code. Có thể dễ dàng thấy được sự hiện diện của hiện tượng này từ các nguồn thông tin trực tuyến có truy vết các từ ngữ thô tục trong mã nguồn.

Quan điểm quy phạm

Có nhiều quan điểm quy phạm khác nhau cùng với những ý kiến lâu đời về chuyện dùng comment sao cho đúng cách trong mã nguồn. Một số trong đó thì mang tính phi chính quy và dựa trên sở thích cá nhân, còn số khác thì được xuất bản hoặc được truyền bá làm hướng dẫn chính quy cho cộng đồng riêng biệt.

Nhu cầu comment

Các chuyên gia không hề có quan điểm cố định về việc liệu có, và khi nào, thích hợp dùng comment trong mã nguồn. Một số thì khẳng định rằng mã nguồn nên có ít comment, trên cơ sở mã nguồn nên có tính tự giải thích hay tự đóng luôn vai trò làm tài liệu. Số khác thì đề ra rằng mã nguồn nên có thật nhiều comment (việc mã nguồn có đến hơn 50% kí tự trừ khoảng trắng ra nằm trong phần comment là chuyện không hiếm gặp).

Giữa những quan điểm đó còn có những lập trường rằng comment bản thân nó chẳng có lợi cũng chẳng có hại, mà viết comment cho chính xác và giữ nó đồng bộ với mã nguồn, và lược bỏ đi nếu nó thừa thãi, không có ích hay gây khó cho bảo trì thì mới là điều đáng nói.

Comment đôi khi được dùng để viết tài liệu cho khế ước trong lối tiếp cận "thiết kế theo khế ước" trong lập trình.

Mức độ chi tiết

Tùy vào đối tượng nhắm đến của code cùng với những cân nhắc khác, mức độ chi tiết và mô tả có thể đổi khác đáng kể.

Ví dụ, comment Java sau đây thì sẽ phù hợp trong bài giới thiệu lập trình cho người mới:

String s = "Wikipedia"; /* Gán giá trị "Wikipedia" vào biến s. */

Nhưng mức độ chi tiết thế này sẽ lại không thích hợp trong bối cảnh của code sản xuất, hay trong những tình huống khác có sự góp mặt của các lập trình viên có kinh nghiệm. Những dòng comment sơ đẳng như vậy là trái với phương châm: "Comment tốt là comment ... làm rõ ý định của code." Hơn nữa, với môi trường code chuyên nghiệp thì mức độ chi tiết được định nghĩa khá rõ ràng để đáp ứng được yêu cầu chỉ tiêu đặc thù do hoạt động nghiệp vụ vạnh ra.

Phong cách

Khi tính xem comment nên được trình bày trong mã nguồn như thế nào thì có khá nhiều phương án sẵn có để lựa chọn. Với những dự án lớn cần đến cả một nhóm phát triển viên thì phong cách comment hoặc là được nhất trí vào trước khi dự án bắt đầu, hoặc là tiến hóa dần tùy theo quy ước hoặc nhu cầu phát sinh khi dự án phát triển lên. Thường thì lập trình viên ưa thích những phong cách mang tính nhất quán, không gây trở ngại, dễ sửa đổi, và khó bị sai sót.

Comment khối

Đoạn code trong C sau đây biểu thị một ví dụ nhỏ cho thấy comment có thể có thay đổi theo nhiều phong cách khác nhau, trong khi vẫn truyền tải cùng một thông tin cơ bản:

/*
     Đây là phần thân comment.
     Biến thể Một.
*/

/***************************\
*                           *
* Đây là phần thân comment. *
* Biến thể Hai.             *
*                           *
\***************************/

Các yếu tố như sở thích cá nhân, tính linh hoạt của công cụ lập trình, và những cân nhắc khác thì có khuynh hướng làm ảnh hưởng lên các biến thể phong cách được sử dụng trong mã nguồn. Ví dụ, Biến thể Hai kia có thể không phải là lựa chọn ưa thích của một số trong số lập trình viên không có trong tay trình soạn thảo mã nguồn mà có tính năng tự động căn chỉnh và dàn bố cục cho văn bản trong comment. Allen Holub, cố vấn phần mềm và là nhà bình luận công nghệ, là một chuyên gia có chủ trương canh chỉnh lề bên trái cho comment:

 /* Đây là phong cách được Holub khuyên dùng cho C và C++
  * Nó được diễn thị trong ''Enough Rope'', trong quy tắc 29.
  */

 /* Đây là một cách làm khác, cũng là trong C.
 ** Trong những trình soạn thảo mà không có tự động thụt một khoảng trắng so với
 ** dòng thứ nhất từ dòng thứ hai đến hết dòng cuối cùng thì cách này dễ hơn.
 ** Cách này cũng được dùng trong sách của Holub, ở quy tắc 31.
 */

Việc sử dụng /* với */ làm dấu định giới cho comment khối là kế thừa từ PL/I vào ngôn ngữ lập trình B – tiền thân trực tiếp của ngôn ngữ lập trình C.

Comment dòng

Comment dòng nói chung dùng dấu định giới hoặc chuỗi token nào đó để biểu thị chỗ bắt đầu của comment, và một kí tự 'dòng mới' để biểu thị chỗ kết thúc của comment.

Trong ví dụ này, toàn bộ phần văn bản từ nhóm kí tự ASCII // tới hết dòng đều bị bỏ qua.

// -------------------------
// Đây là phần thân comment.
// -------------------------

Loại comment như vậy hay bắt đầu từ ngoài cùng bên trái và kéo dài cho cả dòng. Tuy nhiên trong nhiều ngôn ngữ, cũng có thể đặt loại comment này vào chung dòng với dòng lệnh khác, như trong ví dụ Perl sau đây:

print $s . "\n";     # Thêm một ký tự 'dòng mới' sau khi in

Nếu ngôn ngữ cho phép cả comment dòng và comment khối, nhóm lập trình có thể quyết định ra quy ước sử dụng chúng tùy theo hoàn cảnh: ví dụ, chỉ dùng comment dòng để chú thích những vấn đề nhỏ, và dùng comment khối để mô tả những thứ trừu tượng mức cao hơn.

Tag

Lập trình viên có thể sử dụng các tag phi chính quy trong comment để trợ giúp cho việc lập chỉ mục các vấn đề thường thấy. Sau đó có thể tìm kiếm chúng bằng các công cụ lập trình thông dụng như tiện ích grep của Unix, thậm chí là tô sáng cú pháp cho chúng trong trình soạn thảo văn bản. Đôi khi người ta gọi chúng là "codetag" hoặc "token". Các tag như vậy có quy cách không cố định nhưng có thể bao gồm:

• BUG – có bug cần phải được sửa.
• FIXME – cần phải điều chỉnh lại cho đúng.
• HACK – biểu thị giải pháp theo cách "đi đường vòng" vì không có cách nào hay và tốt hơn.
• TODO – điều cần phải được giải quyết.
• NOTE – dùng để làm nổi bật những chỗ cần đặc biệt chú ý vì dễ gây lầm lẫn
• UNDONE – chỗ code là khôi phục lại của code hồi trước.
• XXX – cảnh báo cho các lập trình viên khác về chỗ code có vấn đề hoặc code chỉ sai hướng.

Ví dụ

Ada

Ngôn ngữ lập trình Ada sử dụng '--' để biểu thị comment cho đến hết dòng.

Ví dụ:

  -- the air traffic controller task takes requests for takeoff and landing
   task type Controller (My_Runway: Runway_Access) is
      -- task entries for synchronous message passing
      entry Request_Takeoff (ID: in Airplane_ID; Takeoff: out Runway_Access);
      entry Request_Approach(ID: in Airplane_ID; Approach: out Runway_Access);
   end Controller;

APL

APL sử dụng ⍝ để biểu thị comment cho đến hết dòng.

Ví dụ:

⍝ Now add the numbers:
c←a+b ⍝ addition

Trong các phương ngữ mà có kí hiệu nguyên thủy ⊣ ("left") và ⊢ ("right"), comment thường hay có thể nằm trong hoặc chia tách các phần lệnh ra, "comment" này là ở dạng giá trị string và sẽ được bỏ qua.

d←2×c ⊣'where'⊢ c←a+ 'bound'⊢ b

AppleScript

Đoạn code AppleScript sau đây cho thấy hai phong cách comment được dùng trong ngôn ngữ này:

(*
This program displays a greeting.
*)
on greet(myGreeting)
     display dialog myGreeting & " world!"
end greet

-- Show the greeting
greet("Hello")

BASIC

Trong đoạn code BASIC kinh điển đời đầu này, từ khóa REM được sử dụng để thêm comment.

10 REM This BASIC program shows the use of the PRINT and GOTO Statements.
15 REM It fills the screen with the phrase "HELLO"
20 PRINT "HELLO"
30 GOTO 20

Trong các ngôn ngữ BASIC sau này của Microsoft, bao gồm QuickBASIC, QBasic, Visual Basic, Visual Basic .NET, và VBScript; và trong thế hệ đời sau như FreeBASIC và Gambas, bất kì văn bản nào trên dòng mà nằm sau kí tự ' (dấu nháy đơn) thì đều được coi là comment. Một ví dụ trong Visual Basic .NET:

Public Class Form1
    Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click
        ' The following code is executed when the user
        ' clicks the button in the program's window.
        rem comments still exist.

        MessageBox.Show("Hello, World") 'Show a pop-up window with a greeting
    End Sub
End Class

C

Đoạn code C này diễn thị việc sử dụng comment mở đầu hay comment khối để mô tả mục đích của câu lệnh điều kiện bên dưới. Comment đấy giải thích các từ ngữ và khái niệm chủ đạo, và bao gồm luôn một chữ kí ngắn của lập trình viên là tác giả của đoạn code này.

 /*
  * Check if we are over our maximum process limit, but be sure to
  * exclude root. This is needed to make it possible for login and
  * friends to set the per-user process limit to something lower
  * than the amount of processes root is running. -- Rik
  */
 if (atomic_read(&p->user->processes) >= p->rlim[RLIMIT_NPROC].rlim_cur
     && !capable(CAP_SYS_ADMIN) && !capable(CAP_SYS_RESOURCE))
     goto bad_fork_free;

Kể từ C99 thì cũng đã có thể sử dụng cú pháp // từ C++, biểu thị comment đơn dòng.

Cấu hình Cisco IOS và IOS-XE

Dấu chấm than (!) có thể được dùng để đánh dấu comment trong chế độ cấu hình của bộ định tuyến Cisco, tuy nhiên các comment như vậy không được lưu vào bộ nhớ điện tĩnh (trong đó chứa startup-config), cũng không hề được hiển thị bằng lệnh "show run".

Nhưng vẫn có thể chèn nội dung chú thích mà thực sự trở thành một phần của cấu hình, và có thể được lưu vào startup-config NVRAM thông qua:

• Lệnh "description", dùng để thêm mô tả vào cấu hình của giao diện hoặc của BGP lân cận
• Tham số "name", để thêm lời nhận xét vào một tuyến tĩnh
• Lệnh "remark" trong danh sách truy cập

! Paste the text below to reroute traffic manually
config t
int gi0/2
no shut
ip route 0.0.0.0 0.0.0.0 gi0/2 name ISP2
no ip route 0.0.0.0 0.0.0.0 gi0/1 name ISP1
int gi0/1
shut
exit

ColdFusion

ColdFusion sử dụng comment tương tự như comment của HTML, nhưng thay vì hai dấu nối thì nó dùng ba dấu nối. ColdFusion engine sẽ tự động bỏ qua và không in các comment này lên trình duyệt.

 <!--- This prints "Hello World" to the browser. --->
 <cfoutput>
   Hello World<br />
 </cfoutput>

Fortran IV

Đoạn code Fortran IV này diễn thị cách comment được dùng trong ngôn ngữ đấy (một ngôn ngữ rất thiên về cột văn bản). Chữ cái "C" trong cột 1 khiến toàn bộ dòng được coi là comment.

C
C Dòng bắt đầu bằng 'C' (trong cột 'comment' tức cột đầu tiên) thì là comment
C
      WRITE (6,610)
  610 FORMAT(12H HELLO WORLD)
      END

Lưu ý rằng các cột của một dòng thì ngoài ra được coi như bốn trường: 1 tới 5 là trường nhãn, 6 khiến cho dòng trở thành phần tiếp tục của lệnh trước đó; còn khai báo và các lệnh thì ở từ 7 đến 72.

Fortran 90

Đoạn code Fortran này diễn thị cách comment được dùng trong ngôn ngữ đấy, nội dung comment ở đây mô tả luôn quy tắc định dạng cơ bản.

!* * * * * * * * * * * * * * * * * * * * * * * * * * * *
!* Mọi kí tự sau dấu chấm than đều được coi là comment *
!* * * * * * * * * * * * * * * * * * * * * * * * * * * *
program comment_test
    print '(A)', 'Hello world' ! Fortran 90 hỗ trợ thêm comment nội dòng.
end program

Haskell

Comment dòng trong Haskell bắt đầu bằng '--' (hai dấu nối) cho đến hết dòng, và comment nhiều dòng thì bắt đầu bằng '{-' và kết thúc bằng '-}'.

{- đây là comment
trên nhiều dòng -}
-- còn đây là comment một dòng
putStrLn "Wikipedia"  -- đây cũng là comment một dòng

Haskell cũng cung cấp phương pháp lập trình văn chương để comment, có tên là "Phong cách Bird". Trong đó mọi dòng bắt đầu bằng > thì được coi là code, mọi thứ còn lại thì được coi là comment. Một yêu cầu bổ sung là lập trình viên phải luôn để lại một dòng trắng đằng trước và đằng sau khối code:

Trong Phong cách Bird, bạn phải để lại một dòng trắng đằng trước code.

> fact :: Integer -> Integer
> fact 0 = 1
> fact (n+1) = (n+1) * fact n

Và bạn cũng phải để lại một dòng trắng đằng sau code nữa.

Literate programming can also be done in Haskell, using LaTeX. The code environment can be used instead of the Richard Bird's style: In LaTeX style this is equivalent to the above example, the code environment could be defined in the LaTeX preamble. Here is a simple definition: Cũng có thể làm thế trong Haskell bằng LaTeX. Môi trường code có thể được định nghĩa trong phần tiền ngôn LaTeX. Dưới đây là định nghĩa đơn giản:

\usepackage{verbatim}
\newenvironment{code}{\verbatim}{\endverbatim}

sau đó trong

% the LaTeX source file
The \verb|fact n| function call computes $n!$ if $n\ge 0$, here is a definition:\\
\begin{code}
fact :: Integer -> Integer
fact 0 = 1
fact (n+1) = (n+1) * fact n
\end{code}
Here more explanation using \LaTeX{} markup

Java

Đoạn code Java này cho thấy một comment khối được dùng để mô tả cho phương thức setToolTipText. Cách định dạng ở đây là theo đúng với tiêu chuẩn Javadoc của Sun Microsystems. Comment này được thiết kế để cho bộ xử lý Javadoc đọc.

/**
 * This is a block comment in Java.
 * The setToolTipText method registers the text to display in a tool tip.
 * The text is displayed when the cursor lingers over the component.
 *
 * @param text  The string to be displayed.  If 'text' is null,
 *              the tool tip is turned off for this component.
 */
public void setToolTipText(String text) {
    // This is an inline comment in Java. TODO: Write code for this method.
}

JavaScript

JavaScript sử dụng // đặt trước comment và /* */ để tạo comment nhiều dòng.

// Comment JavaScript một dòng đơn
var iNum = 100;
var iTwo = 2; // Comment ở cuối dòng
/*
comment JavaScript
nhiều dòng
*/

Lua

Ngôn ngữ lập trình Lua sử dụng dấu nối đôi -- cho comment một dòng theo cách tương tự với các ngôn ngữ Ada, Eiffel, Haskell, SQL và VHDL. Lua cũng có comment khối bắt đầu bằng --[[ và chạy cho đến ]] đóng lại.

Ví dụ:

--[[ Comment dài
 nhiều dòng
]]
print(20)   -- in kết quả

Kỷ thuật thông dụng để comment out một đoạn code là bao bọc code giữa --[[ và --]], như sau:

--[[
print(10)
--]]
-- no action (commented out)

Trong trường hợp này, có thể kích hoạt lại code bằng cách thêm một dấu nối đơn vào dòng đầu tiên:

---[[
print(10)
--]]
--> 10

Trong ví dụ đầu tiên, --[[ ở dòng đầu tiên là bắt đầu một comment dài, và hai dấu nối ở dòng cuối vẫn ở bên trong comment đó. Trong ví dụ thứ ba, chuỗi ---[[ bắt đầu một comment một dòng đơn thông thường. Trong trường hợp này, lệnh print nằm ở ngoài comment và dòng cuối cùng trở thành comment độc lập vì nó bắt đầu bằng --.

MATLAB

Trong ngôn ngữ lập trình của MATLAB, kí tự '%' biểu thị comment một dòng. Comment nhiều dòng thì được biểu thị thông qua %{ và %} và có thể lồng vào nhau, ví dụ:

% These are the derivatives for each term
d = [0 -1 0];

%{
  %{
    (Example of a nested comment, indentation is for cosmetics (and ignored).)
  %}
  We form the sequence, following the Taylor formula.
  Note that we're operating on a vector.
%}
seq = d .* (x - c).^n ./(factorial(n))

% We add-up to get the Taylor approximation
approx = sum(seq)

Nim

Nim sử dụng kí tự '#' cho comment nội dòng. Comment khối nhiều dòng mở đầu bằng '#[' và đóng lại bằng ']#', có thể lồng vào nhau.

Nim cũng có comment tài liệu trong đó sử dụng cú pháp đánh dấu pha trộn Markdown và ReStructuredText. Comment tài liệu nội dòng thì dùng '##' còn comment tài liệu khối nhiều dòng thì mở đầu bằng '##[' và đóng lại bằng ']##'. Trình biên dịch có thể tạo sinh ra tài liệu HTML, LaTeX và JSON từ comment tài liệu. Comment tài liệu là một phần của cây cú pháp trừu tượng và có thể được trích xuất bằng macro.

## Tài liệu cho module *ReSTructuredText* và **MarkDown**
# Đây là comment, nhưng không phải là comment tài liệu

type Kitten = object  ## Tài liệu cho kiểu
  age: int  ## Tài liệu cho trường

proc purr(self: Kitten) =
  ## Tài liệu cho hàm
  echo "Purr Purr"  # Đây là comment, nhưng không phải là comment tài liệu

# Đây là comment, nhưng không phải là comment tài liệu

OCaml

OCaml sử dụng comment có thể lồng nhau, có tính hữu ích khi đánh dấu comment cho khối code.

codeLine(* comment mức 1(*comment mức 2*)*)

Pascal

Trong họ ngôn ngữ Pascal của Niklaus Wirth (bao gồm Modula-2 and Oberon), comment được mở đầu bằng '(*' và hoàn tất bằng '*)'. Ví dụ:

(* test diagonals *)
columnDifference := testColumn - column;
if (row + columnDifference = testRow) or
    .......

Trong các phương ngữ hiện đại của Pascal, '{' và '}' được dùng thay thế.

Perl

Comment dòng trong Perl và nhiều ngôn ngữ kịch bản khác thì bắt đầu bằng một kí hiệu dấu thăng (#).

# A simple example
# 
my $s = "Wikipedia"; # Sets the variable s to "Wikipedia".
print $s . "\n";     # Add a newline character after printing

Instead of a regular block commenting construct, Perl uses Plain Old Documentation, a markup language for literate programming, for instance: Thay vì kết cấu comment khối bình thường, Perl sử dụng Plain Old Documentation, một ngôn ngữ đánh dấu cho lập trình văn chương, chẳng hạn:

=item Pod::List-E<gt>new()

Create a new list object. Properties may be specified through a hash
reference like this:

  my $list = Pod::List->new({ -start => $., -indent => 4 });

See the individual methods/properties for details.

=cut

sub new {
    my $this = shift;
    my $class = ref($this) || $this;
    my %params = @_;
    my $self = {%params};
    bless $self, $class;
    $self->initialize();
    return $self;
}

R

R chỉ hỗ trợ comment một dòng bắt đầu bằng kí tự thăng (#).

# Đây là comment
print("Đây không phải là commnet")  # Đây là một comment khác

Raku

Raku (trước đây được gọi là Perl 6) sử dụng comment dòng và comment tài liệu POD theo kiểu giống với Perl chính quy (xem phần Perl phía trên), nhưng thêm một kiểu comment khối có thể cấu hình được: "comment nhiều dòng/nhúng".

Nó bắt đầu bằng một kí tự dấu thăng, rồi một kí tự backtick theo sau, và sau đó là một số kí tự dấu ngoặc mở đầu, rồi kết thúc bằng kí tự dấu ngoặc đóng tương ứng. Nội dung thì có thể không chỉ trải ra nhiều dòng, mà còn có thể được nhúng nội dòng.

#`{{ "commenting out" this version 
toggle-case(Str:D $s)

Toggles the case of each character in a string:

  my Str $toggled-string = toggle-case("mY NAME IS mICHAEL!");

}}

sub toggle-case(Str:D $s) #`( this version of parens is used now ) {
    ...
}

PHP

Comments trong PHP có thể theo kiểu trong C++ (cả nội dòng và khối), hoặc là dùng dấu thăng. PHPDoc là một phong cách phỏng từ Javadoc và là tiêu chuẩn thông dụng để viết tài liệu cho code PHP.

PowerShell

Comment trong Windows PowerShell:

# Comment một dòng
Write-Host "Hello, World!"

<# Comment
   Nhiều
   Dòng    #>

Write-Host "Goodbye, world!"

Python

Comment nội dòng trong Python sử dụng kí tự thăng (#) như trong hai ví dụ trong code sau đây:

# This program prints "Hello World" to the screen
print("Hello World!")  # Note the new syntax

Comment khối về mặt kĩ thuật thì không hề tồn tại trong Python. Chuỗi văn bản literal có thể được dùng cho mục đích tương tự, nhưng trình thông dịch không bỏ qua nó giống như comment dấu "#". Trong ví dụ bên dưới, chuỗi văn bản được bao bọc bằng ba dấu nháy kép đóng vai trò như comment, nhưng còn được xử trí như docstrings:

"""
Assuming this is file mymodule.py, then this string, being the
first statement in the file, will become the "mymodule" module's
docstring when the file is imported.
"""

class MyClass:
    """Docstring cho class"""

    def my_method(self):
        """Docstring cho phương thức"""

def my_function():
    """Docstring cho hàm"""

Ruby

Trong Ruby có comment một dòng, bắt đầu bằng dấu thăng (#):

puts "Đây không phải là comment"

# Đây là comment

puts "Đây không phải là comment"

Comment nhiều dòng đặt giữa từ khóa "begin" và "end":

puts "Đây không phải là comment"

=begin

mọi thứ để trong những dòng này

thì chỉ dành cho con người đọc

=end

puts "Đây là comment"

SQL

Comment tiêu chuẩn trong SQL thì chỉ ở dạng một dòng, bắt đầu bằng hai dấu nối:

-- Đây là comment một dòng
-- kế tiếp bằng một dòng thứ hai
SELECT COUNT(*)
       FROM Authors
       WHERE Authors.name = 'Smith'; -- Ghi chú: ta chỉ cần 'smith'
                                     -- comment này xuất hiện sau code SQL

Còn cách khác thì có cú pháp định dạng comment tương đồng với phong cách "comment khối" được dùng trong C và Java, được hỗ trợ trong Transact-SQL, MySQL, SQLite, PostgreSQL, và Oracle.

MySQL cũng hỗ trợ comment từ kí tự thăng (#) cho đến hết dòng.

Swift

Comment một dòng bắt đầu bằng hai dấu xiên tới (//):

// Đây là comment.

Comment nhiều dòng bắt đầu bằng dấu xiên tới kèm với dấu hoa thị theo sau (/*), và kết thúc bằng dấu hoa thị kèm với dấu xiên tới (*/):

/* Đây cũng là comment
 nhưng được viết ra nhiều dòng. */

Comment nhiều dòng trong Swift có thể được lồng vào các comment nhiều dòng khác. Lập trình viên viết comment lồng nhau bằng cách bắt đầu một khối comment nhiều dòng, rồi bắt đầu một comment nhiều dòng thứ hai bên trong khối đầu tiên. Rồi khối thứ hai được đóng lại, theo sau là quay lại phần của khối thứ nhất:

/* Đây là bắt đầu của comment nhiều dòng thứ nhất.
 /* Đây là comment nhiều dòng thứ hai được lồng vào. */
 Đây là kết thúc của comment nhiều dòng thứ nhất. */

XML (hoặc HTML)

Comment trong XML (hoặc HTML) bắt đầu bằng . Ví dụ:

<!-- select the context here -->
<param name="context" value="public" />

Để tương thích với SGML, chuỗi "--" không được cho phép bên trong comment.

Đọc thêm

• Movshovitz-Attias, Dana and Cohen, William W. (2013) Natural Language Models for Predicting Programming Comments. In Association for Computational Linguistics (ACL), 2013.

Liên kết ngoài

• How to Write Comments, bài do Denis Krukovsky viết
• Source Code Documentation as a Live User Manual do PTLogica viết
• How to Write Comments for the Javadoc Tool