Tạo một tài liệu tiêu chuẩn mã hóa

Tôi làm việc trong một công ty hệ thống điều khiển, nơi công việc chính là SCADA và PLC , cùng với các công cụ hệ thống điều khiển khác.

Phát triển phần mềm không thực sự là điều mà công ty làm, ngoài các bit nhỏ ở đây và đó, cho đến khi có quyết định tạo ra một hệ thống quản lý và thẩm định dự án nội bộ.

Dự án này đã được thực hiện bởi những người đến đây với tư cách là người phần mềm và chúng tôi chủ yếu là đàn em.

Dự án bắt đầu nhỏ, vì vậy chúng tôi chỉ ghi lại các công cụ như thiết kế, công cụ cơ sở dữ liệu, v.v., nhưng chúng tôi chưa bao giờ thực sự đồng ý về một định dạng / quy ước mã hóa.

Chúng tôi đã bắt đầu sử dụng StyleCop để đảm bảo rằng chúng tôi có mã tài liệu tốt, nhưng tôi cảm thấy chúng tôi cần một tài liệu chính thức cho các quy ước / thực hành mã hóa để chúng tôi có thể tiếp tục một tiêu chuẩn tốt và nếu có bất kỳ công việc phát triển chính nào trong tương lai, bất kỳ ai cũng làm việc với nó có một tấm đế tốt.

Vấn đề nằm ở chỗ, tôi không biết làm thế nào để soạn thảo một tài liệu cho các quy ước và tiêu chuẩn mã hóa, tất cả những gì tôi có thể nghĩ là các ví dụ về thực hành tốt và xấu (ví dụ như trường hợp lạc đà khi đặt tên biến, tránh ký hiệu Hungary, v.v.) lập trình viên đủ năng lực (rõ ràng) nhưng chúng tôi không có điều lệ cho loại công cụ này.

Để đưa ra quan điểm về nó, câu hỏi của tôi là: các khía cạnh và nội dung chính của một tài liệu tiêu chuẩn mã hóa tốt là gì?

Các khía cạnh và nội dung chính của một tài liệu tiêu chuẩn mã hóa tốt là gì?

1. Được hỗ trợ bởi các công cụ cho phép tự động kiểm tra mã . Nếu tôi biết rằng tôi không thể cam kết kiểm soát phiên bản bất kỳ đoạn mã nào không phù hợp với một số quy tắc, tôi sẽ được khuyến khích tuân theo các quy tắc đó trong mã của mình. Mặt khác, nếu một số lập trình viên đồng nghiệp đã viết ở đâu đó rằng tôi cần tuân theo một quy tắc, thì tôi không nói tào lao về những quy tắc đó.

2. Được suy nghĩ thấu đáo, thay vì là ý kiến ​​cá nhân của bạn . Bạn không nói đơn giản: "từ giờ trở đi, chúng tôi không sử dụng các vùng nữa, vì tôi không thích các vùng." Thay vào đó, bạn sẽ giải thích rằng các khu vực khuyến khích tăng trưởng mã và không giải quyết bất kỳ vấn đề lớn nào .

   Lý do là trong trường hợp đầu tiên, đồng nghiệp của bạn sẽ trả lời: "tốt, tôi thích các khu vực, vì vậy tôi vẫn sẽ sử dụng chúng". Trong trường hợp thứ hai, mặt khác, nó sẽ buộc những người không đồng ý đưa ra những lời chỉ trích, đề xuất và lập luận mang tính xây dựng, cuối cùng khiến bạn thay đổi quan điểm ban đầu.

3. Được tài liệu tốt . Thiếu tài liệu tạo ra sự nhầm lẫn và không gian để giải thích ; nhầm lẫn và khả năng giải thích dẫn đến sự khác biệt về phong cách, tức là các tiêu chuẩn điều muốn triệt tiêu.

4. Được phổ biến rộng rãi, bao gồm cả bên ngoài công ty của bạn . Một "tiêu chuẩn" được sử dụng bởi hai mươi lập trình viên là ít tiêu chuẩn hơn một tiêu chuẩn được biết đến bởi hàng trăm ngàn nhà phát triển trên toàn thế giới.

Vì bạn đang nói về StyleCop, tôi cho rằng ứng dụng được viết bằng một trong các ngôn ngữ .NET Framework.

Trong trường hợp đó, trừ khi bạn có lý do nghiêm trọng để làm khác đi, hãy tuân thủ các nguyên tắc của Microsoft. Có một số lợi ích trong việc thực hiện nó sau đó tạo ra các tiêu chuẩn của riêng bạn. Lấy bốn điểm trước:

1. Bạn không cần phải viết lại các quy tắc StyleCop để phù hợp với tiêu chuẩn của riêng bạn. Tôi không nói rằng thật khó để viết các quy tắc của riêng bạn, nhưng nếu bạn có thể tránh làm điều đó, điều đó có nghĩa là bạn có nhiều thời gian hơn để làm điều gì đó hữu ích thay thế.

2. Hướng dẫn của Microsoft được suy nghĩ rất tốt. Có nhiều khả năng là nếu bạn không đồng ý với một số trong số họ, có thể là do bạn không hiểu họ. Đây chính xác là trường hợp của tôi; Khi tôi bắt đầu phát triển C #, tôi thấy một vài quy tắc hoàn toàn ngu ngốc. Bây giờ, tôi hoàn toàn đồng ý với họ, vì cuối cùng tôi đã hiểu tại sao họ được viết theo cách này.

3. Các hướng dẫn của Microsoft được ghi chép tốt, vì vậy bạn không phải viết tài liệu của riêng mình.

4. Các nhà phát triển mới, những người sẽ được thuê trong công ty của bạn sau này có thể đã quen thuộc với các tiêu chuẩn mã hóa của microsof. Có một số cơ hội mà không ai sẽ quen thuộc với phong cách mã hóa nội bộ của bạn.

Điều quan trọng đầu tiên cần lưu ý là một tài liệu tiêu chuẩn mã hóa không phải là đúng và sai. Nó không phải là tốt và xấu hay phương pháp nào tốt hơn.

Mục đích của tài liệu tiêu chuẩn mã hóa là đảm bảo rằng tất cả các mã được thiết kế, viết và trình bày giống nhau để giúp nhà phát triển dễ dàng chuyển đổi từ người này sang người khác mà không cần thay đổi tâm lý để đọc phong cách của người khác.

Đó là tất cả về tính đồng nhất, và không có gì về "Đúng và sai"

Với ý nghĩ đó, một số điều bạn nên làm rõ trong tài liệu tiêu chuẩn mã hóa là:

Quy ước đặt tên

Làm thế nào bạn sẽ đặt tên cho phương thức, biến, lớp và giao diện của bạn? Ký hiệu nào bạn sẽ sử dụng?

Ngoài ra, một thứ khác được bao gồm trong các tiêu chuẩn của chúng tôi là một tiêu chuẩn tách rời cho SQL, vì vậy chúng tôi có các tên tương tự cho các bảng, thủ tục, cột, trường id, trình kích hoạt, v.v.

Lõm

Bạn sẽ sử dụng cái gì để thụt đầu dòng? Một tab duy nhất? 3 không gian?

Bố trí

Niềng răng sẽ được giữ trên cùng một dòng với phương pháp mở? (nói chung là java) hoặc trên dòng tiếp theo hoặc một dòng của riêng nó? (nói chung là C #)

Xử lý ngoại lệ / Ghi nhật ký

Các tiêu chuẩn của bạn để xử lý ngoại lệ và ghi nhật ký là gì, tất cả đều được phát triển tại nhà hay bạn đang sử dụng công cụ của bên thứ ba? Nên sử dụng như thế nào?

Bình luận

Chúng tôi có các tiêu chuẩn để ra lệnh chính xác về ngữ pháp và các nhận xét bắt đầu trên dòng trước hoặc sau, không phải trên cùng một dòng, điều này làm tăng khả năng đọc. Ý kiến ​​sẽ phải được thụt vào cùng độ sâu với mã? Bạn sẽ chấp nhận những biên giới nhận xét được sử dụng xung quanh các văn bản lớn hơn?

Làm thế nào về \ \ trên Phương pháp cho mô tả? Đây có phải là để được sử dụng? Khi nào?

Phơi bày

Tất cả các phương thức và trường của bạn có nên thực hiện mức truy cập thấp nhất có thể không?

Cũng là một điều quan trọng cần lưu ý. Một tài liệu tiêu chuẩn tốt có thể đi một chặng đường dài trong việc giúp xem xét mã, nó có đáp ứng các tiêu chuẩn tối thiểu này không?

Tôi hầu như không trầy xước bề mặt của những gì có thể đi vào một trong những tài liệu này, nhưng HÔN

Đừng làm cho nó dài, và nhàm chán, và không thể vượt qua, hoặc những tiêu chuẩn đó sẽ không được tuân theo, hãy giữ cho nó đơn giản.

Tôi đã trải qua quá trình này nhiều lần. Và cách tiếp cận thành công nhất (mặc dù gập ghềnh) là lấy tài liệu "Tiêu chuẩn mã hóa" từ công ty nổi tiếng và sửa đổi nó để phù hợp với nhu cầu của bạn.

Ví dụ: tôi chỉ tìm thấy cái này: http://www.tiobe.com/content/apersinfo/gemrcsharpcs.pdf

Dù sao, giữ cho ngọn lửa của bạn tiện dụng.

Chúc mừng

Tôi ghét hầu hết các tài liệu tiêu chuẩn vì họ thường cố gắng đổ mồ hôi những thứ nhỏ nhặt và bỏ qua bức tranh lớn hơn.

Ví dụ, gần như tất cả trong số họ sẽ nói cách đặt tên biến hoặc dấu ngoặc. Đây là phong cách thuần túy và không thực sự giúp một nhóm các nhà phát triển mã chính xác. Họ bỏ qua những thứ như cấu trúc thư mục và bố trí mã. Tôi đã thấy các tài liệu tiêu chuẩn cho bạn biết chính xác có bao nhiêu khoảng trống giữa các toán tử và bao nhiêu dòng trống để đặt giữa các phương thức. Tất cả những điều này thường kết thúc với vô số ngoại lệ cho quy tắc chỉ cho thấy chúng thực sự vô nghĩa như thế nào, và sau đó chúng quá lớn không ai có thể theo dõi chúng, một lần nữa, tạo ra một sự nhạo báng về điểm mà chúng đang cố gắng thực hiện .

Bây giờ đối với tôi, tôi sử dụng nhiều bit phần mềm khác nhau từ nhiều người khác nhau và tất cả họ đều có phong cách khác nhau. Tôi chỉ đơn giản là quen với điều này, tôi không phàn nàn rằng không có một phong cách chung cho tất cả các nhóm phát triển. Miễn là mã là một phong cách phổ biến trong suốt dự án, tôi thực sự không quan tâm phong cách đó là gì. Vì vậy, quy tắc đầu tiên của tôi cho tất cả các tài liệu tiêu chuẩn là: Giữ một phong cách mã hóa nhất quán trong dự án . không ai nên đưa ra một con số trong đó dấu ngoặc là miễn là tất cả chúng đều giống nhau. Tham gia các cuộc chiến tôn giáo và đẩy chúng :)

Thứ hai là bố trí mã. Khi tôi nhặt một đoạn mã, tôi muốn thấy rằng nó được đặt dọc theo các dòng tương tự như các đoạn công việc tương tự khác. Nếu tôi có một dịch vụ web tôi muốn tên của hợp đồng wsdl rõ ràng, tôi muốn tên của việc thực hiện phải rõ ràng. Tôi không muốn ai đó đưa ra một bố cục hoàn toàn mới và khác biệt cho các tệp và lớp. Điều đó có nghĩa là tôi phải chơi trò "săn mã" gây phiền toái. Nếu nó trông giống như dự án cuối cùng tôi đã làm, tôi có thể biết ngay nơi tìm thấy những gì tôi đang tìm kiếm và đó có lẽ là sự trợ giúp lớn nhất để làm việc với mã của người khác mà tôi biết. Vì vậy, hãy giữ cấu trúc về cách trình bày mã (ví dụ: thư mục Tài liệu cho tài liệu, giao diện cho giao diện, v.v. - bất cứ thứ gì phù hợp với bạn, nhưng hãy tuân theo nó).

Các tạo phẩm mã cũng nên được trình bày, vì vậy bạn cần nói liệu xử lý lỗi dự kiến ​​là ngoại lệ hay mã lỗi - tức là. chức năng kiến ​​trúc tài liệu đang được sử dụng . Nó cũng nên nói loại nhật ký nào sẽ sử dụng và cách trình bày nhật ký / xử lý lỗi cho người dùng hoặc bất kỳ hệ thống con nào được sử dụng để quản lý mã trong tự nhiên. Tôi đã làm việc ở một nơi mà mọi dự án đều ghi nhật ký khác nhau - thật là thảm hại khi mỗi bản phát hành mã phải có tài liệu hoạt động riêng, khác nhau, nói cho các nhân viên của họ biết làm thế nào nếu nó sai. Nhật ký sự kiện, tệp nhật ký (trong trường hợp nào), v.v ... đều hợp lệ ở đây. Điều tương tự cũng áp dụng cho các khía cạnh phổ biến khác đối với mã - cách định cấu hình (không sử dụng tệp .config cho một số chương trình hoặc DB tùy chỉnh hoặc thông số dòng lệnh hoặc đăng ký cho người khác).

Nói tóm lại, điều duy nhất quan trọng là tính nhất quán . Và vì các tài liệu tiêu chuẩn khổng lồ quá nhiều để đọc và ghi nhớ, tôi thích chỉ thông báo cho mọi người về những thứ họ không thể nhìn thấy (ví dụ như các tiêu chuẩn kiến ​​trúc như đăng nhập) và bảo họ giữ mã họ viết phù hợp với những gì hiện có. Và nếu bạn chưa có mã thì bạn không cần một tài liệu tiêu chuẩn! (tốt, không phải cho đến khi bạn viết đủ để làm cho nó hữu ích).

Vì vậy, lấy từ những điểm chính đó: đừng cố tạo ra một tài liệu pháp lý , hãy nghĩ về những thứ không chỉ mã hóa mà còn là cách mã hoạt động và cách mã phù hợp với mong đợi của người khác. Sau đó tin tưởng mọi người làm mã tốt và bạn sẽ thấy họ làm như vậy. (và nếu họ không bạn có thể có lời với họ, không cần phải đặt nó xuống như luật).

Đừng, đó là một sự lãng phí thời gian và năng lượng. StyleCop rất tuyệt và được thành lập qua nhiều năm bởi những người có nhiều kinh nghiệm và thông minh hơn bạn hoặc bất kỳ ai trong nhóm của bạn. Ôm và yêu nó! Nó hướng dẫn bạn liên tục, tốt hơn bất kỳ tài liệu nào đang chờ ai đó có thể bị làm phiền để đọc nó.