Mã nguồn Nhận xét Mẹo tạo kiểu và cách thực hành tốt nhất

Các nhà phát triển đã dành bất kỳ thời gian nào cho các dự án lớn hiểu tầm quan trọng của nhận xét mã. Khi bạn xây dựng nhiều tính năng vào cùng một ứng dụng, mọi thứ có xu hướng trở nên phức tạp. Có rất nhiều bit dữ liệu bao gồm các hàm, tham chiếu biến, giá trị trả về, tham số, bạn dự kiến ​​sẽ theo kịp như thế nào?

Không có gì ngạc nhiên khi nhận xét mã của bạn là điều cần thiết, cả các dự án solo và nhóm. Nhưng nhiều nhà phát triển không biết làm thế nào để đi về quá trình này. Tôi đã phác thảo một số thủ thuật cá nhân của riêng tôi để tạo bình luận mã gọn gàng. Các tiêu chuẩn và mẫu nhận xét sẽ khác nhau giữa các nhà phát triển - nhưng cuối cùng bạn nên cố gắng hướng tới ý kiến ​​sạch sẽ và dễ đọc để giải thích thêm về các khu vực khó hiểu trong mã của bạn.

Chúng ta nên bắt đầu thảo luận về một số khác biệt trong định dạng bình luận. Điều này sẽ cho bạn ý tưởng tốt hơn về mức độ chi tiết bạn có thể trở thành với mã dự án. Sau đó tôi sẽ cung cấp một số mẹo và ví dụ cụ thể mà bạn có thể bắt đầu sử dụng ngay!

Phong cách bình luận: Tổng quan

Cần lưu ý rằng những ý tưởng được trình bày chỉ là hướng dẫn hướng tới ý kiến ​​sạch hơn. Các ngôn ngữ lập trình riêng lẻ không đưa ra các hướng dẫn hoặc thông số kỹ thuật về cách thiết lập tài liệu của bạn.

Điều đó đang được nói, các nhà phát triển thời hiện đại đã nhóm lại với nhau để định dạng hệ thống nhận xét mã của riêng họ. Tôi sẽ cung cấp một vài phong cách chủ đạo và đi vào chi tiết về mục đích của họ.

Bình luận nội tuyến

Thực tế mỗi ngôn ngữ lập trình đều cung cấp bình luận nội tuyến. Chúng được giới hạn trong nội dung một dòng và chỉ nhận xét văn bản sau một điểm nhất định. Vì vậy, ví dụ trong C / C ++, bạn bắt đầu nhận xét nội tuyến như thế này:

// bắt đầu liệt kê biến var myvar = 1; 

Điều này là hoàn hảo để chuyển vào mã trong vài giây để giải thích chức năng có thể gây nhầm lẫn. Nếu bạn đang làm việc với nhiều tham số hoặc chức năng gọi, bạn có thể đặt một loạt các bình luận nội tuyến gần đó. Nhưng công dụng có lợi nhất là giải thích đơn giản cho chức năng nhỏ.

if (callAjax ($ params)) // chạy thành công callAjax với các tham số người dùng Mã Code

Lưu ý trên tất cả các mã sẽ cần phải nằm trên một dòng mới sau dấu ngoặc mở. Nếu không, tất cả sẽ bị bắt trên cùng một dòng bình luận! Tránh quá nhiệt tình vì bạn thường không cần phải xem các bình luận một dòng trên khắp trang của mình, nhưng đặc biệt đối với các mối nối khó hiểu trong mã của bạn, những điều này dễ dàng hơn nhiều để thả vào phút cuối.

Khối mô tả

Khi bạn cần bao gồm một lời giải thích lớn nói chung, một lớp lót sẽ không thực hiện được mẹo. Có các mẫu nhận xét được định dạng trước được sử dụng trong mọi lĩnh vực lập trình. Khối mô tả đáng chú ý nhất được nhìn thấy xung quanh các chức năng và các tập tin thư viện. Bất cứ khi nào bạn thiết lập một chức năng mới, đó là một thực hành tốt để thêm một khối mô tả ở trên khai báo.

/ ** * @desc mở một cửa sổ phương thức để hiển thị thông báo * @param chuỗi $ dir - thông báo sẽ được hiển thị * @return bool - thành công hay thất bại * / function modalPopup ($ dir) mật 

Trên đây là một ví dụ đơn giản về một nhận xét chức năng mô tả. Tôi đã viết một hàm có lẽ bằng JavaScript được gọi là modalPopup trong đó có một tham số duy nhất. Trong các nhận xét ở trên, tôi đã sử dụng một cú pháp tương tự như phpDocumentor trong đó mỗi dòng được đặt trước một @ biểu tượng theo sau là một phím được chọn. Những điều này sẽ không ảnh hưởng đến mã của bạn theo bất kỳ cách nào, vì vậy bạn có thể viết @sự miêu tả thay vì @desc không có thay đổi gì.

Những phím nhỏ này thực sự được gọi là thẻ nhận xét được ghi lại rất nhiều trên trang web. Hãy tự trang điểm và sử dụng chúng như bạn muốn trong suốt mã của mình. Tôi thấy họ giúp giữ cho mọi thứ trôi chảy Tôi có thể kiểm tra thông tin quan trọng trong nháy mắt. Bạn cũng nên chú ý rằng tôi đã sử dụng / * * / định dạng bình luận kiểu khối. Điều này sẽ giữ mọi thứ sạch sẽ hơn nhiều hơn là thêm một dấu gạch chéo bắt đầu ở mỗi dòng.

Nhận xét nhóm / lớp

Ngoài việc bình luận các chức năng và các vòng lặp, các khu vực khối không được sử dụng thường xuyên. Nơi bạn thực sự cần mạnh mẽ chặn bình luận đứng đầu các tài liệu phụ trợ hoặc các tệp thư viện của bạn. Thật dễ dàng để tìm ra tất cả và viết tài liệu vững chắc cho mọi tệp trong trang web của bạn - chúng ta có thể thấy thực tiễn này trong nhiều CMS như WordPress.

Khu vực trên cùng của trang của bạn sẽ chứa các bình luận liên quan đến chính tệp. Theo cách này bạn có thể nhanh chóng kiểm tra nơi bạn đang chỉnh sửa khi làm việc trên nhiều trang cùng một lúc. Ngoài ra, bạn có thể sử dụng khu vực này như cơ sở dữ liệu cho các chức năng quan trọng nhất bạn sẽ cần ra khỏi lớp.

/ ** * @desc lớp này sẽ giữ các chức năng cho tương tác người dùng * ví dụ bao gồm user_pass (), user_username (), user_age (), user_regdate () * @ Tác giả Jake Rocheleau jakerocheleau @ gmail * @required settings.php * / lớp trừu tượng myWebClass  

Bạn có thể thấy tôi chỉ sử dụng một lớp mẫu nhỏ cho hàng giả myWebClass mã. Tôi đã thêm một số thông tin meta với tên và địa chỉ email của tôi để liên lạc. Khi các nhà phát triển đang viết mã nguồn mở, đây thường là cách thực hành tốt để những người khác có thể liên hệ với bạn để được hỗ trợ. Đây cũng là một phương pháp vững chắc khi làm việc trong các nhóm phát triển lớn hơn.

Tag @cần thiết không phải là thứ tôi đã thấy được sử dụng ở nơi khác. Tôi đã theo kịp định dạng trong một vài dự án của mình, chỉ trên các trang mà tôi đã tùy chỉnh rất nhiều phương pháp. Bất cứ khi nào bạn đưa các trang vào một tệp, chúng phải đến trước khi bạn xuất bất kỳ mã nào. Vì vậy, thêm các chi tiết này vào khối nhận xét lớp chính là một cách tốt để nhớ những tập tin nào là cần thiết.

Bình luận mã mặt trước

Bây giờ chúng tôi đã bao gồm 3 mẫu nhận xét quan trọng, hãy xem xét một vài ví dụ khác. Có nhiều nhà phát triển lối vào đã chuyển từ HTML tĩnh sang mã jQuery và CSS. Nhận xét HTML không có mục đích so với các ứng dụng lập trình, nhưng khi bạn viết thư viện kiểu và tập lệnh trang, mọi thứ có thể trở nên lộn xộn theo thời gian.

JavaScript tuân theo một phương pháp bình luận truyền thống hơn tương tự như Java, PHP và C / C++. CSS chỉ sử dụng các nhận xét kiểu khối được mô tả bằng dấu gạch chéo và dấu hoa thị. Bạn nên nhớ rằng các nhận xét sẽ được hiển thị công khai cho khách truy cập của bạn, vì cả CSS và JS đều không được phân tích cú pháp phía máy chủ, nhưng một trong hai phương pháp này hoạt động rất tốt để để lại các thông tin bổ ích trong mã của bạn để quay lại.

Cụ thể việc phá vỡ các tệp CSS có thể là một việc vặt. Chúng ta đều quen thuộc với việc để lại một bình luận nội tuyến để giải thích một bản sửa lỗi cho Internet Explorer hoặc Safari. Nhưng tôi tin rằng nhận xét CSS có thể được sử dụng ở cấp độ jQuery và PHP sử dụng chúng. Hãy đi sâu vào việc tạo các nhóm kiểu trước khi chạm vào một số mẹo chi tiết để nhận xét mã.

Nhóm phong cách CSS

Đối với những người đã thiết kế CSS trong nhiều năm, nó gần như là bản chất thứ hai. Bạn từ từ ghi nhớ tất cả các thuộc tính, cú pháp và xây dựng hệ thống của riêng bạn cho các bảng định kiểu. Thông qua công việc của riêng tôi, tôi đã tạo ra những gì tôi gọi nhóm để ghép các khối CSS tương tự thành một khu vực.

Khi quay trở lại để chỉnh sửa CSS, tôi có thể dễ dàng tìm thấy những gì tôi cần trong vài giây. Cách bạn chọn để nhóm các phong cách hoàn toàn phụ thuộc vào bạn, và đó là vẻ đẹp của hệ thống này. Tôi đã có một vài tiêu chuẩn định sẵn mà tôi đã nêu ra dưới đây:

• @resets - lấy đi các lề trình duyệt mặc định, phần đệm, phông chữ, màu sắc, v.v..
• @fonts - đoạn văn, tiêu đề, blockquote, liên kết, mã
• @navulation - các liên kết điều hướng trang web cốt lõi
• @layout - Trình bao bọc, thùng chứa, thanh bên
• @header & @footer - những thứ này có thể thay đổi dựa trên thiết kế của bạn. Các kiểu có thể bao gồm các liên kết và danh sách không có thứ tự, cột chân trang, tiêu đề, điều hướng phụ

Khi nhóm các bảng định kiểu tôi đã tìm thấy hệ thống gắn thẻ có thể giúp rất nhiều Tuy nhiên, không giống như PHP hay JavaScript, tôi sử dụng một @nhóm theo sau là một danh mục hoặc từ khóa. Tôi đã bao gồm 2 ví dụ dưới đây để bạn có thể cảm nhận được ý của tôi.

/ ** @group footer * / #footer style '

/ ** @group chân trang, phông chữ nhỏ, cột, liên kết ngoài ** / 

Bạn có thể thay thế thêm một chút chi tiết bổ sung trong mỗi khối nhận xét. Tôi chọn giữ mọi thứ đơn giản và dễ hiểu vì vậy các bảng định kiểu rất dễ lướt qua. Bình luận là tất cả về tài liệu, miễn là bạn hiểu văn bản đó là tốt để đi!

4 mẹo để tạo kiểu bình luận tốt hơn

Chúng tôi đã dành nửa đầu của bài viết này để xem các định dạng khác nhau để bình luận mã. Bây giờ chúng ta hãy thảo luận về một số mẹo tổng thể để giữ cho mã của bạn sạch sẽ, có tổ chức và dễ hiểu.

1. Giữ mọi thứ có thể đọc được

Đôi khi là nhà phát triển, chúng ta quên mất rằng chúng tôi đang viết bình luận cho con người đọc. Tất cả các ngôn ngữ lập trình mà chúng tôi hiểu là được xây dựng cho máy móc, vì vậy việc chuyển đổi thành văn bản đơn giản có thể rất tẻ nhạt. Điều quan trọng cần lưu ý là chúng tôi không ở đây để viết một bài nghiên cứu cấp đại học, nhưng chỉ để lại lời khuyên!

function getTheMail () // code ở đây sẽ xây dựng e-mail / * chạy mã nếu hàm gọi sendMyMail () tùy chỉnh của chúng tôi trả về true find sendMail () trong /libs/mailer. class.php và tin nhắn được gửi! * / if (sendMyMail ()) trả về true; // giữ đúng và hiển thị thành công trên màn hình

Thậm chí chỉ một vài từ là có còn hơn không. Khi bạn quay lại để chỉnh sửa và thực hiện các dự án trong tương lai, điều đáng ngạc nhiên là bạn sẽ quên bao nhiêu. Vì bạn không nhìn vào cùng một biến và tên hàm mỗi ngày, bạn có xu hướng dần quên đi phần lớn mã của mình. Như vậy bạn có thể không bao giờ để lại quá nhiều ý kiến! Nhưng bạn có thể để lại quá nhiều bình luận xấu.

Như một quy tắc chung, dành chút thời gian để tạm dừng và suy ngẫm trước khi viết. Tự hỏi mình đi Điều gì là khó hiểu nhất về chương trình và làm thế nào bạn có thể giải thích nó tốt nhất trong “hình nộm” ngôn ngữ? Cũng xem xét tại sao bạn viết mã chính xác như bạn.

Một số lỗi khó hiểu nhất bật lên khi bạn quên mục đích của các chức năng được tạo tùy chỉnh (hoặc bên thứ 3). Để lại dấu vết nhận xét dẫn trở lại một vài tệp khác Nếu điều này sẽ giúp bạn nhớ chức năng dễ dàng hơn.

2. Làm giảm bớt một số không gian!

Tôi không thể nhấn mạnh đủ tầm quan trọng của nó khoảng trắng có thể. Cái này đi đôi khi đúng cho các nhà phát triển PHP và Ruby, những người đang làm việc trên các trang web lớn với hàng trăm tệp. Bạn sẽ nhìn chằm chằm vào mã này cả ngày! Sẽ không tuyệt sao nếu bạn chỉ lướt qua những khu vực quan trọng?

$ dir1 = "/ nhà /"; // đặt thư mục nhà chính $ myCienDir = getCurDirr (); // đặt thư mục người dùng hiện tại $ userVar = $ get_username (); // tên người dùng hiện tại

Trong ví dụ trên, bạn sẽ nhận thấy phần đệm thêm mà tôi đã đặt giữa các nhận xét và mã trên mỗi dòng. Khi bạn đang cuộn qua các tệp, kiểu nhận xét này sẽ rõ ràng nổi bật. Nó làm cho việc tìm lỗi và sửa mã của bạn dễ dàng hơn hàng trăm lần khi các khối biến là như vậy dọn dẹp.

Bạn có thể thực hiện một tác vụ tương tự đối với mã bên trong hàm mà bạn bối rối về cách thức hoạt động của nó, nhưng phương pháp này cuối cùng sẽ làm lộn xộn mã của bạn với các nhận xét nội tuyến và điều đó hoàn toàn ngược lại với trật tự! Tôi đề nghị trong kịch bản này thêm một nhận xét dòng lớn xung quanh khu vực logic.

$ (tài liệu). yet (function () $ ('. sub'). hide (); // ẩn điều hướng phụ trên pageload / ** kiểm tra sự kiện nhấp chuột trên một neo bên trong .itm div ngăn chặn liên kết mặc định hành động để trang không thay đổi khi nhấp vào truy cập phần tử cha của .itm, theo sau là danh sách .sub tiếp theo để chuyển đổi mở / đóng ** / $ ('. itm a'). live ('click', function (e ) e.preventDefault (); $ (this) .parent (). next ('. sub'). slideToggle ('fast');););

Đây là một chút mã jQuery nhắm mục tiêu điều hướng trượt menu phụ. Nhận xét đầu tiên là nội tuyến để giải thích lý do tại sao chúng tôi đang ẩn tất cả .phụ các lớp học. Phía trên trình xử lý sự kiện nhấp trực tiếp Tôi đã sử dụng một nhận xét khối và thụt lề tất cả các văn bản đến cùng một điểm. Điều này làm cho mọi thứ đẹp hơn thay vì các đoạn chạy - đặc biệt là cho những người khác đọc bình luận của bạn.

3. Nhận xét trong khi mã hóa

Cùng với khoảng cách thích hợp, đây có thể là một trong những thói quen tốt nhất để có được. Không ai muốn quay lại chương trình của họ sau khi nó hoạt động và ghi lại từng phần. Hầu hết chúng ta thậm chí không muốn quay lại và ghi lại những khu vực khó hiểu! Nó thực sự tốn rất nhiều công sức.

Nhưng nếu bạn có thể viết bình luận trong khi bạn đang viết mã mọi thứ sẽ vẫn tươi mới trong tâm trí bạn. Thông thường các nhà phát triển sẽ bị mắc kẹt trong một vấn đề và tìm kiếm các giải pháp đơn giản nhất trên web. Khi bạn nhấn vào khoảnh khắc Eureka và giải quyết vấn đề như vậy, nhìn chung có một khoảnh khắc rõ ràng nơi bạn hiểu các lỗi trước đó của mình. Đây sẽ là thời điểm tốt nhất để lại bình luận cởi mở và trung thực về mã của bạn.

Ngoài ra, điều này sẽ cho bạn thực hành làm quen với việc bình luận tất cả các tệp của bạn. Lượng thời gian cần thiết để quay lại và tìm hiểu cách thức hoạt động của một thứ gì đó lớn hơn nhiều sau khi bạn đã xây dựng chức năng. Cả bản thân tương lai của bạn và đồng đội của bạn sẽ cảm ơn bạn vì đã để lại bình luận trước thời hạn.

4. Xử lý lỗi Buggy

Tất cả chúng ta không thể ngồi trước máy tính hàng giờ để viết mã. Tôi cho rằng chúng ta có thể thử, nhưng đến một lúc nào đó chúng ta cần ngủ! Bạn có thể sẽ phải chia tay với mã của mình trong ngày với một số tính năng vẫn bị hỏng. Trong kịch bản này, điều quan trọng là bạn để lại những bình luận dài, chi tiết về nơi bạn bỏ đi.

Ngay cả sau một giấc ngủ đêm mới, bạn có thể ngạc nhiên với việc khó có thể quay trở lại vào vòng xoáy của tiền mã hóa. Ví dụ: nếu bạn đang xây dựng một trang tải lên hình ảnh và phải để nó chưa hoàn thành, bạn nên bình luận về nơi mà trong quá trình bạn rời đi. Là những hình ảnh tải lên và được lưu trữ trong bộ nhớ tạm thời? Hoặc có thể chúng thậm chí không được nhận dạng trong hình thức tải lên hoặc có thể chúng không được hiển thị đúng trên trang sau khi tải lên.

Nhận xét lỗi là quan trọng vì hai lý do chính. Đầu tiên bạn có thể dễ dàng chọn nơi bạn rời đi và cố gắng làm mới tâm trí để khắc phục (các) vấn đề. Và thứ hai bạn có thể phân biệt giữa phiên bản sản xuất trực tiếp của trang web của bạn và cơ sở thử nghiệm. Hãy nhớ rằng bình luận nên được sử dụng để giải thích lý do tại sao bạn làm một cái gì đó, không chính xác những gì nó làm.

Phần kết luận

Phát triển cho các ứng dụng và phần mềm web là một thực tiễn đầy đủ, mặc dù khó khăn. Nếu bạn là một trong số ít các nhà phát triển thực sự hiểu về phần mềm xây dựng thì điều quan trọng là phải trưởng thành với các kỹ năng mã hóa của bạn. Để lại bình luận mô tả chỉ là thực hành tốt trong thời gian dài, và bạn sẽ không bao giờ hối tiếc!

Nếu bạn có đề xuất cho nhận xét mã rõ ràng hơn, hãy cho chúng tôi biết trong khu vực thảo luận bên dưới!