Điều gì nên có trong một tiêu chuẩn mã hóa tốt (đọc: hữu ích)?
Câu trả lời:
Một lý do cho mọi yêu cầu. Bằng cách này, theo tiêu chuẩn không trở thành một kiểu sùng bái hàng hóa và mọi người biết rằng thay đổi tiêu chuẩn nếu lý do không còn áp dụng hoặc vi phạm tiêu chuẩn trong các trường hợp cụ thể mà lý do rõ ràng không áp dụng .
Tab vs Spaces! Tôi nhận được cập nhật điên rồ khi một trong những đồng nghiệp của tôi vô tình cam kết rất nhiều tab để không gian chuyển vào kho lưu trữ
Quy ước đặt tên
EDIT: Bằng cách này, tôi có nghĩa là Hướng dẫn đặt tên, không đặt tên Quy tắc.
Ví dụ, một Hướng dẫn sẽ là All boolean values should begin with Is/Can/Has/etc when possible. Một quy tắc sẽ làAll boolean values must start with Is
IsCanUpdatevà IsHasChildren. Chắc chắn, đó là sai, nhưng đó là nghị định trong tiêu chuẩn. Và đây là quan điểm của tôi: một khi bạn bắt đầu chỉ định những điều này, bạn phải đảm bảo rằng bạn bao quát tất cả các cơ sở, nếu không mọi người sẽ chạy theo một cái gì đó mà tiêu chuẩn không bao gồm, hoặc che đậy xấu, và sau đó họ sẽ viết một cái gì đó sai, hoặc họ bắt đầu bỏ qua các tiêu chuẩn. Dù bằng cách nào, đội thua cuộc.
Một tiêu chuẩn mã hóa cho một nhóm nên bao gồm các tùy chọn trình biên dịch cho các cảnh báo và lỗi phải được giải quyết.
Các lập trình viên nên được tự do tăng cảnh báo cho mã của riêng họ, nhưng phải có một đường cơ sở để việc đọc và làm việc với mã của người khác không làm lộn xộn đầu ra bạn nhận được từ trình biên dịch.
Một tiêu chuẩn như vậy cũng sẽ phải giải quyết làm thế nào các lập trình viên có thể vô hiệu hóa các cảnh báo theo từng trường hợp như vậy, nếu có một đoạn mã đặc biệt không tuân thủ theo cách khác.
Một số tiêu chuẩn tôi thích (tôi biết có rất nhiều trong số chúng, nhưng đó là những tiêu chuẩn tôi thích):
Tiêu chuẩn mã hóa giúp một chút khi bạn viết mã lần đầu tiên, chúng giúp ích rất nhiều khi bạn hoặc người thay thế của bạn phải cập nhật mã 2 năm sau đó.
Tiêu chuẩn lý tưởng dẫn đến mã nơi bạn có thể chuyển đến bất kỳ trang tùy ý nào trong mã và hiểu chính xác những gì nó đang làm trong lần đọc đầu tiên, bởi vì
Mặt khác, quá nhiều tiêu chuẩn tùy ý có thể làm gián đoạn dòng chảy của mã viết. Vì vậy, tôi tin rằng mọi mục trong một quy ước mã hóa được đề xuất nên được đánh giá theo 2 tiêu chí sau:
Nếu không đúng, mục này chỉ là tùy ý và có thể không cần thiết
Tôi sẽ bao gồm những điều sau đây trong một tiêu chuẩn tôi viết:
Cho rõ ràng:
Tổ chức tệp: Chỉ định một thứ tự cố định cho các mục trong tệp cho phép nhóm dễ dàng điều hướng các tệp khác. Bạn không cần phải tìm kiếm #defines hoặc định nghĩa cấu trúc.
Quy ước đặt tên: Hỗ trợ đặt tên nhất quán dễ đọc. Nhưng tránh chỉ định quá nhiều quy tắc, điều đó gây hại cho khả năng ghi.
Cấu trúc mã. Vị trí Brace xoăn, mức độ thụt lề, khoảng trắng so với tab, v.v ... Vâng, đây có thể là một sở thích cá nhân mạnh mẽ, nhưng mục tiêu là mã rõ ràng. Tìm tùy chọn tốt nhất cho nhóm và gắn bó với nó.
Đối với chính xác:
Thực tiễn tốt nhất cụ thể cho loại vấn đề của bạn: Quy tắc về cấp phát bộ nhớ, hoặc đồng thời hoặc tính di động.
"Const Correctnesss", sử dụng hợp lý staticvà volatilevv
Các quy tắc về macro tiền xử lý và các tính năng dễ bị lạm dụng khác của ngôn ngữ.
Những ý tưởng truyền cảm hứng, thực dụng khiến mọi người phải suy nghĩ, thay vì những hạn chế tiêu cực khiến mọi người ngừng suy nghĩ.
Nếu không, bạn nhận được những con khỉ mã sợ đi sau những quả chuối .
Điều gì nên có trong một tiêu chuẩn mã hóa? Càng ít càng tốt. Ít hơn là nhiều hơn. Và với sự biện minh, xin vui lòng.
Không phải vì tôi là một lập trình viên cao bồi không muốn xử lý, mà bởi vì tôi đã thấy các thông số mã hóa nặng không có logic đằng sau nó (có lẽ) "Tôi đã tìm thấy điều này trên 'Net ở đâu đó vào năm 95" mà cuối cùng lại trở thành một cơn ác mộng quan liêu để làm việc với.
Một số người thành thật dường như tin rằng bằng cách nâng cao các tiêu chuẩn, họ sẽ thấy sự gia tăng tương ứng về "chất lượng" mã và có lẽ bằng biện pháp đó họ sẽ làm. Trong khi đó, họ sẽ bỏ qua kiến trúc, hiệu suất, ý thức chung và một loạt những thứ khác cuối cùng quan trọng hơn số lượng dòng trong một tệp.
Một số ý nghĩa thông thường cũ sẽ không đi được; có quá nhiều tài liệu tiêu chuẩn mã hóa lao động vào các điểm không liên quan (các mục như loại phông chữ và kích thước là một trong những tài liệu cực đoan hơn tôi từng thấy).
Điều tốt nhất để làm nếu bạn trong một nhóm các nhà phát triển là nói chuyện với nhau và xem mã của bạn, hình thành sự đồng thuận về những gì được chấp nhận và nếu bạn cần viết ra những điểm chính làm hướng dẫn, nhưng hãy giữ chúng như chỉ cần hướng dẫn. Nếu bạn không thể biện minh cho bất kỳ sự khác biệt nào từ các hướng dẫn, bạn thực sự nên xem xét lý do tại sao bạn thực hiện nó.
Vào cuối ngày, mã rõ ràng và dễ hiểu là quan trọng hơn bất kỳ quy tắc cứng nhắc nào về bố cục hoặc kiểu chữ.
Như những người khác đã đề cập, bảo hiểm kiểm tra mã là quan trọng. Tôi cũng muốn xem:
Cơ cấu dự án. Các bài kiểm tra là một phần của mã, hay chúng nằm trong một thư mục dự án / gói / riêng biệt? Mã UI có tồn tại với các công cụ back-end không? Nếu không, nó được ngăn cách như thế nào?
Quá trình phát triển. Viết bài kiểm tra trước khi viết mã? Liệu sửa chữa các bản dựng bị hỏng có ưu tiên hơn phát triển? Khi nào các đánh giá mã được thực hiện, và chúng nên bao gồm những gì?
Quản lý mã nguồn. Điều gì được kiểm tra khi nào? Các tài liệu thiết kế và kế hoạch kiểm tra có được kiểm soát không? Khi nào bạn phân nhánh và khi nào bạn gắn thẻ? Bạn có giữ các bản dựng trước đó không, và nếu có bao nhiêu / trong bao lâu?
Tiêu chuẩn triển khai. Làm thế nào là một bản dựng được đóng gói? Những gì cần phải đi vào ghi chú phát hành? Các kịch bản nâng cấp được tạo / kiểm soát / chạy như thế nào?
Quên tất cả những điều tào lao về quy ước đặt tên, định dạng và số lượng dòng có thể có trong một hàm / phương thức / mô-đun. Một quy tắc: sử dụng bất cứ kiểu nào hiện có trong bất cứ thứ gì bạn đang chỉnh sửa. Nếu bạn không thích phong cách của ai đó, hãy chọn nó trong phần đánh giá mã. Ngoại lệ duy nhất có thể là điều tab-vs-space, nếu chỉ vì nhiều trình soạn thảo / IDE sẽ chuyển đổi một cách mù quáng sang cái khác, và sau đó bạn sẽ phá hủy lịch sử thay đổi của mình vì mỗi dòng đã thay đổi.
Tôi nghĩ rằng thực sự có hai điều cần giải quyết, và trên thực tế tôi sẽ xem xét chúng một cách riêng biệt bởi vì chúng không thể được tiếp cận theo cùng một cách, mặc dù tôi thấy cả hai đều quan trọng.
Khía cạnh kỹ thuật tôi đủ điều kiện của Tiêu chuẩn mã hóa , cũng như Herb Sutter và Andrei Alexandrescu với Tiêu chuẩn mã hóa C ++ của họ . Bài thuyết trình tôi đủ điều kiện về Phong cách mã hóa , bao gồm quy ước đặt tên, thụt lề, v.v ...
Tiêu chuẩn mã hóa
Bởi vì nó hoàn toàn là kỹ thuật, Tiêu chuẩn mã hóa có thể chủ yếu là khách quan. Vì vậy, mọi quy tắc nên được hỗ trợ bởi một lý do. Trong cuốn sách tôi đã đề cập đến mỗi mục có:
Cơ sở lý luận và ngoại lệ là rất quan trọng, vì chúng tóm tắt lý do tại sao và khi nào.
Tiêu đề phải đủ rõ ràng để trong quá trình đánh giá, người ta chỉ cần có một danh sách các tiêu đề (bảng cheat) để làm việc. Và rõ ràng, nhóm các mục theo thể loại để dễ dàng tìm ra một mục.
Sutter và Alexandrescu quản lý để có một danh sách chỉ một trăm mặt hàng, mặc dù C ++ được coi là có lông;)
Kiểu mã hóa
Phần này nói chung là ít khách quan hơn (và có thể hoàn toàn chủ quan). Mục đích ở đây là để đảm bảo tính nhất quán, bởi vì điều này giúp người bảo trì và người mới đến.
Bạn không muốn tham gia vào một cuộc chiến tranh thần thánh về phong cách thụt đầu dòng hoặc niềng răng tốt hơn ở đây, có những diễn đàn cho việc này: vì vậy trong danh mục này bạn làm mọi việc bằng sự đồng thuận> bỏ phiếu đa số> quyết định tùy ý của nhà lãnh đạo.
Để biết ví dụ về định dạng, hãy xem danh sách các tùy chọn của Phong cách nghệ thuật . Lý tưởng nhất là các quy tắc phải rõ ràng và đầy đủ để một chương trình có thể viết lại mã (mặc dù không chắc là bạn sẽ không bao giờ viết mã;))
Đối với quy ước đặt tên, tôi sẽ cố gắng làm cho lớp / loại dễ dàng phân biệt với các biến / thuộc tính.
Cũng trong danh mục này, tôi phân loại các "biện pháp" như:
Linh tinh?
Và như là một từ cuối cùng, có một mục hiếm khi được thảo luận trong Tiêu chuẩn mã hóa, có lẽ vì nó đặc biệt đối với mỗi ứng dụng: tổ chức mã. Vấn đề kiến trúc có lẽ là vấn đề nổi bật nhất, làm hỏng thiết kế ban đầu và bạn sẽ bị ảnh hưởng bởi nó từ nhiều năm nay. Có lẽ bạn nên thêm một phần để xử lý tệp cơ bản: tiêu đề công khai / riêng tư, quản lý phụ thuộc, tách mối quan tâm, giao tiếp với các hệ thống hoặc thư viện khác ...
Nhưng đó không là gì nếu chúng không thực sự được áp dụng và thi hành .
Bất kỳ vi phạm nào sẽ được đưa ra trong quá trình đánh giá mã và không có đánh giá mã nào sẽ ổn nếu vi phạm là nổi bật:
Rõ ràng, thay đổi một quy tắc có nghĩa là nhận được "đi trước" từ các nhà lãnh đạo.
Tôi thích định dạng trong Nguyên tắc thiết kế khung, nó bao gồm một phần chung và các lý do cho các hướng dẫn. Bit hữu ích nhất là các chi tiết bắt đầu bằng Do, Do, Tránh và Xem xét.
Dưới đây là một ví dụ trong phần Thực hiện các Thành viên Giao diện Rõ ràng nó có các mục sau (lưu ý rằng tôi đã bỏ các lý do vì lợi ích)
Tránh thực hiện các thành viên giao diện một cách rõ ràng mà không có lý do mạnh mẽ để làm như vậy
Xem xét thực hiện các thành viên giao diện một cách rõ ràng nếu các thành viên dự định chỉ được gọi thông qua giao diện.
Không sử dụng các thành viên rõ ràng như một ranh giới bảo mật.
Đừng cung cấp một thành viên ảo được bảo vệ cung cấp chức năng tương tự như> thành viên được triển khai rõ ràng nếu chức năng này được dành riêng cho các lớp dẫn xuất.
Điều này tạo ra một giai điệu chung tốt. Bằng cách sử dụng Tránh và Xem xét, bạn có thể cho phép các nhà phát triển sử dụng phán đoán của họ. Ngoài ra bởi vì chúng là hướng dẫn và không phải là quy tắc, các nhà phát triển có thể thấy chúng hợp lý hơn và đến lượt chúng có nhiều khả năng tuân theo chúng hơn.
Dường như không ai đề cập đến bảo mật - trong một tiêu chuẩn mã hóa, bạn phải tham khảo các yêu cầu mã bảo mật (ví dụ: việc sử dụng các mô đun xác thực đầu vào, không cho phép các chức năng yếu đã biết như strcpy, yêu cầu xử lý lỗi, v.v.)
Ví dụ. Các ví dụ gọn gàng, không tầm thường, gần gũi với thế giới thực sử dụng mọi quy tắc. Nhận xét (không nhất thiết là một phần của mã) phần nào của ví dụ tuân theo quy tắc nào.
Mẫu. Không phải loại C ++, nhưng một cái gì đó để sao chép-dán và điền trực tiếp. Sẽ dễ dàng hơn nhiều để có được nhận xét soạn thảo 24 dòng ngay khi bạn có một tài liệu tham khảo để sao chép từ đó.
Tính năng số một: Tối đa tuyệt đối hai trang.
Đây là điều bạn muốn mọi nhà phát triển đọc và ghi nhớ. Bạn không cần phải tra cứu tiêu chuẩn mỗi khi bạn cần viết một hàm mới (hoặc tệ hơn là một dòng mới). Vì vậy, hãy giữ nó ngắn gọn và chỉ giữ các quy tắc thực sự cung cấp giá trị gia tăng cho sản phẩm cuối cùng.
Tiêu chuẩn mã hóa thực sự là một số mặt hàng:
Quy ước mã hóa
Thực hành tốt nhất
cho người cũ Không bao giờ để trống Bắt sau khi thử
try { Foo(); } catch { //do nothing }
1) Nếu có một ngoại lệ do Foo () ném ra, nó có thể gây ra các vấn đề khác về các chức năng tiếp theo, điều đó cho rằng foo đã thành công.
2) Trình xử lý lỗi toàn cầu sẽ không thông báo cho nhóm hỗ trợ ngoại lệ khi xảy ra trên prod
Môi trường mã hóa
Các tiêu chuẩn mã hóa, khi được viết trên giấy, chỉ có rất nhiều hiệu quả. Tôi thích nó như thế nào Go đang xuất bản tiêu chuẩn mã hóa của nó. Nó có công cụ gofmtđịnh dạng văn bản chương trình thành một định dạng. Bất kỳ cuộc tranh luận nào về định dạng mã hóa sau đó sẽ chỉ dẫn đến một bản vá cho các nguồn của gofmt.
Đối với định dạng nên có,
if, thân hàm, khối lệnh cho bất kỳ mục đích nào khác,Khi tôi đang đọc mã (phần lớn ngôn ngữ C) của người khác, nếu tên biến / hàm không trực quan trong ngữ cảnh của dự án hoặc nếu vượt quá năm cấp độ thụt lề hoặc hàm thì có hơn sáu hoặc bảy đối số hoặc một hàm chạy qua Hai hoặc ba trang trên màn hình, việc đọc và hiểu mã trở nên rất khó khăn. Khi được yêu cầu thực hiện các cải tiến / bảo trì công việc trên nó, nó chỉ làm tăng thêm khó khăn. Nó làm cho tôi muốn gofmtchương trình được viết cho mọi dự án (hoặc thậm chí ngôn ngữ) và mọi tệp mã nguồn được chạy qua chương trình đó trước khi nó được cam kết vào dự án.
Tôi thích Hướng dẫn về Phong cách Google JavaScript .
Nó ngắn gọn trong hướng dẫn của nó nhưng có chi tiết nếu bạn cần chúng.