Tài liệu tiêu chuẩn

Question

Tôi đang viết một tài liệu tiêu chuẩn mã hóa cho một nhóm khoảng 15 nhà phát triển có tải dự án từ 10 đến 15 dự án mỗi năm. Trong số các phần khác (mà tôi có thể đăng bài ở đây khi tôi nhận được chúng) Tôi đang viết một phần về định dạng mã. Vì vậy, để bắt đầu, tôi nghĩ rằng đó là khôn ngoan rằng, vì lý do nào, chúng tôi thiết lập một số tiêu chuẩn định dạng/đặt tên mã cơ bản, nhất quán.

Tôi đã xem xét khoảng 10 dự án được viết trong 3 năm qua từ nhóm này và tôi, rõ ràng là việc tìm kiếm một loạt các phong cách khá rộng. Các nhà thầu vào và ra và đôi khi, và đôi khi thậm chí tăng gấp đôi kích thước đội.

Tôi đang tìm một vài gợi ý về định dạng mã và đặt tên tiêu chuẩn đã thực sự được đền đáp ... nhưng điều đó cũng có thể thực sự được biện minh. Tôi nghĩ tính nhất quán và các mẫu chia sẻ đi một chặng đường dài để làm cho mã dễ bảo trì hơn ... nhưng, có những thứ khác mà tôi nên cân nhắc khi xác định các tiêu chuẩn đã nói không?

• Làm cách nào để bạn đặt dấu ngoặc đơn? Bạn có thực hiện theo cùng nguyên tắc về dấu ngoặc đơn khi giao dịch với các lớp học, phương pháp, thử các khối catch, câu lệnh chuyển đổi, nếu khối khác, v.v.

• Bạn có xếp hàng các trường trên một cột không? Bạn có chú ý/tiền tố biến riêng với dấu gạch dưới không? Bạn có tuân theo bất kỳ quy ước đặt tên nào để giúp dễ dàng tìm thấy các chi tiết cụ thể trong một tệp không? Làm thế nào để bạn đặt hàng các thành viên trong lớp của bạn?

Còn đề xuất về không gian tên, bao bì hoặc thư mục mã nguồn/tiêu chuẩn tổ chức thì sao? Tôi có xu hướng bắt đầu với một cái gì đó như:

<com|org|...>.<company>.<app>.<layer>.<function>.ClassName 

Tôi tò mò muốn xem có thực hành nào khác được chấp nhận hơn những gì tôi đã quen - trước khi tôi liên doanh ra các tiêu chuẩn này. Các liên kết đến các tiêu chuẩn đã được xuất bản trực tuyến cũng sẽ rất tuyệt vời - mặc dù tôi đã thực hiện một chút điều đó.

Answer 1

Trước tiên, hãy tìm trình định dạng mã tự động hoạt động với ngôn ngữ của bạn. Lý do: Dù tài liệu nói gì, mọi người chắc chắn sẽ phá vỡ các quy tắc. Việc chạy mã thông qua trình định dạng dễ dàng hơn nhiều so với việc chọn nit-pick trong một đánh giá mã.

Nếu bạn đang sử dụng một ngôn ngữ có tiêu chuẩn hiện tại (ví dụ: Java, C#), cách dễ nhất là sử dụng ngôn ngữ đó hoặc ít nhất bắt đầu với ngôn ngữ đó là bản nháp đầu tiên. Sun đặt rất nhiều suy nghĩ vào các quy tắc định dạng của họ; bạn cũng có thể tận dụng lợi thế của nó.

Trong mọi trường hợp, hãy nhớ rằng nhiều nghiên cứu đã chỉ ra rằng những thứ khác nhau như vị trí cú đúp và khoảng trắng không có hiệu quả đo lường về năng suất hoặc khả năng hiểu hay tỷ lệ lỗi. Chỉ cần có bất kỳ tiêu chuẩn nào là chìa khóa.

Answer 2

Nó rõ ràng là khác nhau tùy thuộc vào ngôn ngữ và công nghệ. Bởi cái nhìn của không gian tên ví dụ của bạn tôi sẽ đoán java, trong trường hợp đó http://java.sun.com/docs/codeconv/ là một nơi thực sự tốt để bắt đầu. Bạn cũng có thể muốn xem xét một cái gì đó giống như cấu trúc thư mục chuẩn của maven mà sẽ làm cho tất cả các dự án của bạn trông giống nhau.

Answer 3

Tôi sẽ đề nghị thứ hai của Jason.

Tôi vừa hoàn thành tài liệu chuẩn cho nhóm 10-12 hoạt động chủ yếu trong perl. Tài liệu nói để sử dụng "thụt đầu dòng giống như perltidy cho các cấu trúc dữ liệu phức tạp". Chúng tôi cũng cung cấp cho tất cả mọi người các cài đặt mẫu perltidy sẽ dọn sạch mã của họ để đáp ứng tiêu chuẩn này.Nó rất rõ ràng và rất nhiều tiêu chuẩn công nghiệp cho ngôn ngữ, do đó chúng tôi đã rất vui khi được nhóm nghiên cứu mua lại.

Khi đặt ra để viết tài liệu này, tôi hỏi xung quanh một số ví dụ về mã tuyệt vời trong kho lưu trữ của chúng tôi và googled một chút để tìm các tài liệu tiêu chuẩn khác mà kiến ​​trúc sư thông minh hơn tôi xây dựng một mẫu. Đó là khó khăn là súc tích và thực dụng mà không đi vào lãnh thổ quản lý vi mô nhưng rất đáng giá; có bất kỳ tiêu chuẩn nào thực sự là quan trọng.

Hy vọng nó hoạt động!

Answer 4

Đến từ ngành công nghiệp ô tô, đây là một vài tiêu chuẩn phong cách sử dụng vì lý do cụ thể:

niềng răng Luôn sử dụng trong cấu trúc điều khiển, và đặt chúng trên dòng riêng biệt. Điều này giúp loại bỏ các vấn đề với những người thêm mã và bao gồm cả mã hoặc không bao gồm nhầm lẫn bên trong cấu trúc điều khiển.

if(...) 
{ 

} 

Tất cả các nút chuyển/chọn có trường hợp mặc định. Trường hợp mặc định sẽ ghi lại lỗi nếu đó không phải là đường dẫn hợp lệ.

Vì lý do tương tự như trên, bất kỳ cấu trúc điều khiển nào khác nếu ... elseif ... phải kết thúc bằng một mặc định khác cũng ghi nhật ký lỗi nếu đó không phải là đường dẫn hợp lệ. Một câu lệnh if nếu không yêu cầu điều này.

Trong trường hợp không thường xuyên khi một vòng lặp hoặc cấu trúc điều khiển được cố tình trống, dấu chấm phẩy luôn được đặt bên trong để cho biết rằng đây là cố ý.

while(stillwaiting()) 
{ 
    ; 
} 

Tiêu chuẩn đặt tên có kiểu rất khác nhau cho typedef, hằng số được xác định, biến toàn cục mô-đun, v.v ... Tên biến bao gồm loại. Bạn có thể nhìn vào tên và có một ý tưởng tốt về những gì mô-đun nó liên quan đến, phạm vi và loại của nó. Điều này giúp bạn dễ dàng phát hiện các lỗi liên quan đến các loại, v.v.

Có những thứ khác, nhưng đây là những đầu lỗi của tôi.

-Adam