it-swarm-vi.com

Là viết bình luận bên trong phương pháp không phải là một thực hành tốt?

Một người bạn nói với tôi rằng viết bình luận bên trong phương pháp là không tốt. Ông nói rằng chúng ta chỉ nên có ý kiến ​​cho các định nghĩa phương thức (javadocs) chứ không phải bên trong thân phương thức. Có vẻ như anh ta đọc trong một cuốn sách có ý kiến ​​bên trong mã có nghĩa là có vấn đề trong mã. Tôi không hiểu lý lẽ của anh ấy. Tôi nghĩ rằng viết bình luận bên trong thân phương thức là tốt và nó giúp các nhà phát triển khác hiểu nó tốt hơn và nhanh hơn. Vui lòng cung cấp ý kiến ​​của bạn.

63
Srini Kandula

Bạn của bạn đã sai, và rất ít lập trình viên sẽ đồng ý với anh ta. Bạn nên viết bình luận bất cứ khi nào và bất cứ nơi nào bạn cảm thấy họ hiểu rõ nhất.

151
mqp

Mặc kệ bạn của bạn. Bình luận khi cần thiết. Nhưng nỗ lực để làm cho mã của bạn tự giải thích, để nhận xét không cần thiết. Hãy nhớ rằng máy tính của bạn không thực hiện nhận xét và vì vậy thật dễ dàng để các bình luận không đồng bộ với những gì đang diễn ra.

Tôi có xu hướng sử dụng một khối bình luận để giải thích một chút logic đặc biệt khó hiểu, nếu không sẽ mất một chút xoắn não để đọc. Và sau đó tôi sẽ cố gắng làm cho logic rõ ràng hơn và loại bỏ nhu cầu giải thích.

90
Michael Petrotta

Mã tốt là tự viết tài liệu. Một phương thức nên thực hiện chính xác một điều, và một điều nên rõ ràng bằng tên phương thức và thông số kỹ thuật nhận xét. Do đó, cần có ý kiến ​​trong phương pháp giải thích logic cho thấy phương pháp này nên được chia thành các phương thức trách nhiệm duy nhất.

Bây giờ, cho thực tế. Bạn đang phải đối mặt với một codebase mã spaghetti phức tạp và bạn đang cố gắng trở nên tốt đẹp với những người bảo trì. Bạn không có thời gian hoặc bắt buộc phải cấu trúc lại 8 triệu dòng mã và ngay cả khi bạn đã làm, sẽ có những sắc thái vì mọi thứ đều phức tạp. Bạn làm nghề gì?

44
Mark Peters

Tôi ngạc nhiên khi có nhiều người không đồng ý với quan điểm này.

  1. Mã tốt nên tự viết tài liệu, vì vậy bạn nên cẩn thận chọn tên phương thức, tên biến, v.v.
  2. Phương pháp của bạn không được dài đến mức bạn không thể thấy toàn bộ phương thức và các nhận xét trong một màn hình

Điều đó nói rằng, có ngoại lệ. Nhưng họ là ngoại lệ. Và điểm quan trọng là ngoại lệ, đó là số ít. Bạn thực sự chỉ cần giải thích mã nội tuyến nếu bạn đang làm một cái gì đó phản trực giác.

Một tình huống điển hình mà bạn có thể cần nhận xét trong phương pháp của mình là khi bạn áp dụng hack cục bộ để tối ưu hóa tốc độ, nhưng lần đọc đầu tiên có thể mang đến cho một lập trình viên khác một khoảnh khắc wtf. Đó là một điểm tốt để thêm một bình luận.

Nhưng nói chung: không, không thêm nhận xét trong phương thức của bạn.

24
markijbema

Tôi nghĩ anh ấy đang nói về một trường hợp như thế này:

public void upload() {
    // destination Host
    String Host = ....
}

Nơi bạn có thể làm cho mã tốt hơn bằng cách có một tên biến rõ ràng hơn, thay vì nhận xét:

public void upload() {
    String destinationHost = ....
}
18
Douglas

Tôi tin rằng bạn của bạn đang đề cập đến "Mã sạch" của Robert C. Martin. Tuy nhiên, tôi nghĩ anh ấy đang quá đơn giản hóa tình hình một chút. Cuốn sách nói về việc đưa ra các phương pháp tên rõ ràng và mô tả, mà tất cả chúng ta nên biết, nhưng không bao giờ có thể lặp lại đủ. Cuốn sách cũng khuyên bạn nên tạo ra các phương thức rất nhỏ bằng cách gói bất kỳ khối mã nào có thể được đặt tên rõ ràng và mô tả thành một phương thức của riêng nó. Vì vậy, nếu bạn cảm thấy rằng một khối mã cần một nhận xét giải thích những gì nó làm, thì bạn nên làm cho nó một phương thức riêng biệt với một tên thích hợp. Về lý thuyết, nếu tất cả các phương thức của bạn dưới 5 dòng và nếu tất cả chúng đều có tên mô tả tốt, thì rõ ràng những gì chúng làm mà không cần phải giải thích nó trong một nhận xét.

Tuy nhiên, điều đó không có nghĩa là bạn không bao giờ nên có ý kiến ​​trong các phương pháp của mình. Vấn đề là ý kiến ​​không nên thừa. Họ nên thêm thông tin. Nếu bạn có một phương thức thực hiện chính xác một điều và điều đó rõ ràng từ tên của nó, thì bạn không cần bình luận giải thích những gì nó làm. Tuy nhiên, nó có ý nghĩa hoàn hảo để có một bình luận giải thích lý do tại sao nó làm điều đó theo cách đặc biệt đó. Bạn có thể muốn một bình luận giải thích lý do tại sao bạn chọn một thuật toán trên một thuật toán khác hoặc tại sao bạn chọn một cấu trúc dữ liệu trên một thuật toán khác. Nói cách khác, bạn muốn chính mã giải thích cách thức hoạt động của nó và bạn muốn các ý kiến ​​giải thích lý do cho các quyết định thiết kế của bạn, i. e. Tại sao mọi thứ được thực hiện theo cách đặc biệt này.

Cuốn sách khuyên bạn nên tái cấu trúc mã xấu thay vì bình luận nó. Đây chắc chắn là một ý tưởng tuyệt vời trong lý thuyết, nhưng trong thực tế, bạn có thể không có thời gian hoặc cơ sở hạ tầng, chẳng hạn như khung kiểm tra đơn vị làm việc với bộ kiểm tra đơn vị thích hợp để thực hiện điều đó. Có những lúc bạn phải đối mặt với một cơ sở mã lộn xộn, mà bạn cần phải làm việc ngày hôm qua, và cách duy nhất để tiến về phía trước là cố gắng hiểu các phần lộn xộn, và nhận xét chúng như một cách để ghi chú cho chính bạn.

16
Dima

Có, bạn chắc chắn viết bình luận bên trong các phương thức trong Java.

Như quy ước mã của Sun nói:

Các chương trình Java có thể có hai loại ý kiến: nhận xét triển khai và nhận xét tài liệu. Nhận xét triển khai là những nhận xét được tìm thấy trong C++, được phân định bởi /*...*///. Nhận xét tài liệu (được gọi là "nhận xét tài liệu") chỉ dành cho Java và được phân tách bằng /**...*/. Nhận xét tài liệu có thể được trích xuất thành các tệp HTML bằng công cụ javadoc.

Vì vậy, các ý kiến ​​trong phương pháp là ý kiến ​​thực hiện.

8
zengr

Tôi hoàn toàn không đồng ý với bạn của bạn và cho rằng các bình luận hàm nội tuyến là một phần rất quan trọng để viết mã tốt. Các bình luận hàm được thiết kế để giúp khách hàng của mã hiểu rõ hơn về những gì mã phải làm - các tham số và giá trị trả về của nó có ý nghĩa gì, các loại bất biến mà nó dự kiến ​​sẽ có khi vào và thoát, v.v. được hướng chủ yếu vào những người duy trì mã và lý tưởng là một loạt các ghi chú tinh thần cho tác giả ban đầu của mã. Họ làm cho nó có thể nhìn vào một phương pháp phức tạp mà một người khác đã đọc và hiểu được những gì tác giả ban đầu đang nghĩ. Chúng cũng giúp chẩn đoán lỗi dễ dàng hơn, vì nếu các bình luận mô tả ý định của mã là gì và giả định mà nó tạo ra, có thể dễ dàng hơn nhiều để tìm ra cách một đoạn mã bị lỗi khi phát hiện sự cố.

Cá nhân tôi thấy các bình luận nội tuyến hữu ích vì họ buộc tôi phải chứng minh với bản thân rằng mã tôi sắp viết sẽ hoạt động chính xác. Thông thường, tôi sẽ tạo thói quen không viết bất kỳ mã nào mà không bình luận rõ ràng trước ý định là gì và nó sẽ hoạt động như thế nào. Nhiều lần hơn không, điều này ngăn tôi khỏi những lỗi ngớ ngẩn trong mã bởi vì tôi thấy rằng lời giải thích của tôi không chính xác hoặc không tính đến một số trường hợp Edge.

Tất nhiên, mọi người đều có kỷ luật mã hóa riêng và có lẽ một số người thấy viết mã dễ dàng hơn mà không cần nhận xét nội tuyến và thay vào đó chia mã thành nhiều phương thức nhỏ hơn. Tuy nhiên, từ kinh nghiệm tôi đã thấy rằng nhận xét nội tuyến là vô giá trong quá trình phát triển và gỡ lỗi, và cực kỳ hữu ích cho những người khác phải xem qua và duy trì mã của tôi sau khi tôi chuyển sang dự án khác.

6
templatetypedef

Bạn của bạn cũng có thể bày tỏ quan điểm rằng các bình luận, nếu không phải là "mùi mã", thì " khử mùi ". Điều này không cụ thể đối với các nhận xét trong phương thức, nhưng nó có thể có xu hướng xác thực các nhận xét trong phương thức hơn các nhận xét mở đầu.

Khi bạn viết một bình luận, thông thường đó là để giải thích một cái gì đó. Khi một cái gì đó cần giải thích - tốt, nó không tự giải thích. Mã tuyệt vời tự giải thích. Vì vậy, khi bạn thêm nhận xét, bạn đang che đậy sự thất bại của mình để tự giải thích, mà không làm cho nó tự giải thích. Vì vậy, mỗi khi bạn viết một nhận xét như vậy, thay vì thay đổi mã - bằng cách đổi tên, bằng cách trích xuất phương thức, v.v. - thành làm cho nó tự giải thích, bạn đang thiếu lý tưởng.

Nhưng tất cả chúng ta đều thiếu sự hoàn hảo bây giờ và một lần nữa. Và thường tốt hơn là thêm một nhận xét giải thích hơn là để lại mã khó hiểu không có giấy tờ.

6
Carl Manaster

Ý kiến ​​tốt giải thích tại sao không làm thế nào. Đó là điểm khác biệt chính ở đây. Hầu hết mọi người sẽ có thể làm theo những gì bạn đang làm nhưng tại sao bạn làm điều đó đòi hỏi phải có thêm nhận xét. Những ý kiến ​​nên gần với hoạt động càng tốt.

3
Bill Leeper

Khi nhận xét mã của bạn (hoặc mã được ghi lại rất tệ của người khác), bạn có thể thường xuyên phải đối mặt với cảm giác tuyệt đối ghê tởm , ghét hoặc phẫn nộ . Mã có thể hành xử theo những cách bực bội và bất ngờ và bạn có thể phải thêm một số hack rất xấu để làm cho nó hoạt động cho một số thời hạn.

Trong tất cả các trường hợp thể hiện cảm xúc của bạn bằng cách chú thích các phần mã tương ứng với một số từ ngữ nặng nề (xem linux kernelcountcount ) là cách làm phổ biến. Những nhận xét đó phải nằm trong các phương thức để chúng không xuất hiện trong API được tạo tài liệu tự động, do đó, cả sếp và khách hàng của bạn cũng như bất kỳ người bất khả tri nào khác sẽ không nhìn thấy nó.

Tuy nhiên, các lập trình viên đồng nghiệp của bạn sẽ cảm thấy nhẹ nhõm hạnh phúc khi nghiên cứu nguồn . (Và tất nhiên bạn có thể thêm ghi chú cho chính mình hoặc sử dụng mã nguồn làm phương tiện liên lạc ở một mức độ nào đó, #TODO: add more examples here)

Tất nhiên bạn có thể tranh luận rằng những loại bình luận này không được phép xuất hiện ở nơi đầu tiên, hoặc chúng nên bị xóa trước khi phát hành cuối cùng, nhưng những dự án phần mềm ngày nay có chu kỳ phát hành rất ngắn và một số bình luận vẫn còn liên quan nhiều bản dựng hàng đêm sau đó, vì vậy có lẽ bạn của bạn nên bắt đầu học đọc (và viết) giữa các dòng .

2
codecraft

Thật tuyệt khi có mã mà không cần bình luận. Khi bạn nhận được, lưu và xóa mọi thứ, chúng tôi có một ý tưởng khá hay về những gì đang diễn ra và không cần bình luận.

Đôi khi mã trở nên lộn xộn và là một ứng cử viên để tái cấu trúc, vì vậy bạn có thể phải nhận xét trong thời gian trung bình.

Hôm nay tôi có một dòng mã không làm những gì được mong đợi. Rõ ràng một dữ liệu .net không nghĩ rằng một hàng được nhập là một bản ghi mới. Khi bạn chèn các bản ghi từ bảng không có gì xảy ra. Hàng được nhập phải thay đổi trạng thái trước. Một nhận xét đơn giản là tất cả những gì cần thiết, vì vậy khi tôi quay lại 6 tháng kể từ bây giờ và nghĩ, "Tôi cần cái quái gì để làm gì?" Tôi sẽ biết.

1
JeffO

Đó là thực tế phổ biến cho các lập trình viên để đưa ra nhận xét bên trong các phương thức bất cứ khi nào họ nghĩ rằng nó không rõ ràng cho các lập trình viên khác những gì mã đang làm. Đôi khi các lập trình viên cũng đưa ra các bình luận TODO bên trong phương thức này. Tuy nhiên, sự thật là nếu bạn có quá nhiều bình luận bên trong các phương thức, bạn có thể cần phải lùi lại và suy nghĩ nếu bạn đang làm những việc quá phức tạp hơn mức cần thiết. Trong Word khác, có lẽ bạn muốn tránh bình luận về một điều hiển nhiên cho các lập trình viên khác vì việc đọc mã với họ khó hơn.

Để đề xuất bạn bè của bạn một cách tích cực, bạn nên nhớ rằng chúng ta có thể tránh bình luận quá nhiều bằng cách đặt tên cho các biến và phương thức đúng cách và giữ cho mỗi phương thức nhỏ và đảm bảo rằng họ không làm quá nhiều nhân viên.

1
knoguchi

Tôi nghĩ lý do anh ta nói là vì anh ta tin rằng các chức năng nên đủ ngắn để mỗi người chỉ gói gọn trong một hoạt động khái niệm duy nhất.

Tôi không nhất thiết phải đăng ký niềm tin đó đến mức cực đoan (vì nhiều lý do, bao gồm cả việc đọc mã như vậy có thể trở thành ác mộng), nhưng nếu có, có thể họ sẽ chỉ có một nhận xét cho mỗi chức năng, vì chỉ có một nhận xét một khái niệm cho mỗi chức năng và một nhận xét cho mỗi khái niệm.

Dù bằng cách nào, tôi sử dụng nhận xét bất cứ khi nào và bất cứ nơi nào có mã mà sự lựa chọn hoặc hành vi của họ không rõ ràng ngay lập tức - thường phải thực hiện với các cân nhắc về hiệu suất hoặc toán bí truyền. Những thứ đó thường không liên quan ngay đến người tiêu dùng của chức năng, vì vậy tôi cho rằng trên thực tế, đó là một ý tưởng tốt để che giấu nó khỏi tài liệu.

1
Rei Miyasaka

Tôi tin rằng bạn của bạn đã nói về javadoc, sẽ tạo tài liệu từ nhận xét của bạn nếu nó ở trên phần khai báo phương thức của bạn (và được trang trí thêm dấu hoa thị) như thế này:

/**
   get a webpage for a given url 
   @param url: the url to get
   @returns String: the http-source 
*/
public String getWebpage (String url) {
... 

Nếu bạn đặt bình luận này bên trong phương thức thì nó vô dụng.

Do đó - như một quy tắc chung: đặt các bình luận vào Java phía trên phương thức.

Trường hợp ngoại lệ có thể và sẽ xảy ra. Tôi đồng ý: sử dụng các phương pháp ngắn, viết mã tự ghi. Tuy nhiên, javadoc là một công cụ khuyến khích sự trùng lặp các bình luận, bởi vì nó khác trông rất trần trụi trong tài liệu này. :)

1
user unknown

Tôi thừa nhận rằng trong một phương thức được viết từ đầu, người ta chỉ có thể ghi lại chức năng của nó trong tiêu đề. Tuy nhiên.

Tôi thấy rằng các bình luận thường được chèn vào nơi phát hiện ra lỗi và một sắc thái tinh tế đã bị bỏ qua ngay cả khi phương thức chỉ có một trách nhiệm duy nhất - điều đó thành thật, hiếm khi xảy ra trong mã kế thừa. Hơn nữa, tôi thấy không có lý do gì để có một tên biến dài bốn mươi ký tự (ngay cả khi nó chỉ được sử dụng ở hai nơi) khi một tên biến ngắn hơn với một nhận xét ngắn gọn có thể dễ dàng tiêu hóa và sử dụng lại sau này. Sạch sẽ và súc tích là tốt nhất, nhưng trên hết, đó là một phương tiện giao tiếp với các lập trình viên khác cũng như email, thư và thơ cũng vậy. Và thêm vào đó tôi thêm trích dẫn:

Tôi chỉ viết thư này lâu hơn vì tôi không có thời gian để viết ngắn hơn.

Blaise Pascal, (1623-1662) Lettres tỉnh

1
M. Tibbits

Nhận xét chỉ làm cho mã thân thiện hơn với lập trình viên, hãy nhớ các bình luận sẽ không được thực thi.

Nếu bạn đã đọc mã của mình sau vài tháng, các bình luận sẽ giúp việc đọc qua mã dễ dàng hơn.

Nó sẽ làm cho mã có thể duy trì và bất kỳ lập trình viên nào khác nhìn vào mã sẽ thấy dễ hiểu logic bạn đã triển khai.

Điều đó không có nghĩa là bạn phải luôn thêm nhận xét ngay cả đối với một phương thức có vài dòng mã.

Ví dụ như đoạn mã sau là tự giải thích và không yêu cầu bất kỳ bình luận nào để làm cho chức năng của nó rõ ràng

public String getName(){
    return name;
}

Trong khi một phương thức lớn, hãy thêm nhận xét để dễ đọc hơn bất cứ khi nào bất kỳ lập trình viên nào nhìn vào nó.

Hãy nhớ trong khi mã hóa, bạn có thể nghĩ rằng mã là tự giải thích, nhưng khi bạn có thể xem nó sau sáu tháng, các ý kiến ​​bạn đã thêm sáu tháng trước chắc chắn sẽ giúp bạn hoặc bất kỳ lập trình viên nào khác hiểu mã nhanh chóng.

0
Alpine

Vấn đề với các bình luận nội tuyến là chúng phải được duy trì cùng với mã (cũng đúng với các nhận xét hàm/phương thức/mô-đun/cấp độ lớp, nhưng không phải là mức độ lớn); Chúa mới biết có bao nhiêu mã nguồn vẫn còn ở đó, nơi các bình luận hoàn toàn không liên quan gì đến mã mà họ ghi lại nữa, mà IMO cũng tệ hoặc tệ hơn là không có bất kỳ bình luận nào.

Tốt nhất, tài liệu nội tuyến nên được giới hạn trong các tình huống sau:

  • Giải thích mã được tối ưu hóa mạnh mẽ hoặc "khó hiểu", cùng với lời biện minh cho tại sao mã được tối ưu hóa rất nhiều hoặc "khó khăn" ("chúng tôi đã thiếu yêu cầu về hiệu năng X và hồ sơ cho thấy nút cổ chai ở đây phần; tối ưu hóa dưới đây đã đạt được hiệu suất Y% ");

  • Đề cập đến một tiêu chuẩn hoặc yêu cầu ("Khoảng cách bài đăng DTED 0 là 30 giây giây");

  • Xác định mã cần phân tích/phát triển hơn nữa ("TODO");

Luật đầu tiên của tài liệu mã - không tài liệu rõ ràng. Hệ quả của luật đầu tiên về tài liệu mã - viết mã rõ ràng đến mức lớn nhất có thể.

0
John Bode

Đầu tiên, câu hỏi của bạn là hướng Java cụ thể - điều này ảnh hưởng đáng kể đến câu trả lời.

Lượng bình luận đó là bắt buộc liên quan nhiều đến ngôn ngữ mà bạn đang làm việc.

  • Một số ngôn ngữ như Java và C # cho vay rất tốt đối với khái niệm mã tự viết tài liệu. sau đó chỉ thêm nhận xét nội tuyến cho những nội dung mà bạn không thể mô tả nguyên bản trong ngôn ngữ.

  • Một số ngôn ngữ như SQL khó đọc hơn. Cú pháp, thứ tự đánh giá, lồng nhau, v.v có thể khiến cho việc thiết kế theo cách tự viết tài liệu trở nên khó khăn hơn. Cách tiếp cận cơ bản tương tự vẫn được áp dụng: tập trung vào việc sử dụng ngôn ngữ càng nhiều càng tốt, sau đó thêm nhận xét để bù cho các khu vực không rõ ràng hoặc khó hiểu.

Nhìn chung, bạn không thể xóa bỏ 100% bình luận, nhưng mục tiêu của bạn là xóa cần để nhận xét càng nhiều càng tốt bằng cách làm cho mã tự mô tả nhiều hơn. Kết quả của những nỗ lực này thường là ít mã tổng thể và mã được tổ chức tốt hơn. Bất kể có hay không vẫn còn các bình luận, điều này có nghĩa là mã của bạn sẽ dễ bảo trì và dễ tiếp cận hơn nhiều - đó thực sự là những gì các bình luận có ý định hỗ trợ trong bất kỳ vấn đề nào.

0
STW

Ý tưởng rằng Javadoc (hoặc thậm chí gợi ý tự động hoàn thành Delphi) nên thay đổi cách mã số người (ngoài việc thêm chức năng cho javadoc) là khá vô lý.

Hỏi bạn của bạn đã đến trước, javac hay javadoc?

Giống như hỏi cái nào đến trước, con bò hay bà O'Leary


Ngoài ra, javadoc nên dành cho những người thực hiện lớp và chức năng của bạn, các nhận xét trong mã dành cho những người đang duy trì mã của bạn. Đặc biệt với các phương thức riêng tư của bạn, không ai nhất thiết phải nhìn vào mã của bạn để xem nó làm gì. Đó là những gì tài liệu dành cho. Nhưng nếu ai đó cần Tweak một cái gì đó vì một lỗi do một lỗi, thì bạn muốn nhận xét điều đó trong phương pháp của bạn.

Rõ ràng là anh ta giả định 90% mã trong thực tế là sửa lỗi đều xấu. Tôi chưa bao giờ đọc "Lập trình viên thực dụng" nhưng tôi có thể cho rằng anh ta không tham khảo cuốn sách đó.

0
Peter Turner

Tôi sẽ ném hai xu của mình bây giờ rằng bữa tiệc đã kết thúc tốt đẹp. Tôi sử dụng các nhận xét khi tôi mô tả một chút logic kinh doanh cụ thể hoặc khi tôi phải thêm một cái gì đó để bao quát một trường hợp Edge khó chịu.

Mã phát triển theo thời gian để giải thích cho những điều chưa biết trước đó và vì vậy khi bạn áp dụng hỗ trợ băng tần, thay vì cho rằng nó được biết đến tại sao bạn đặt hỗ trợ ban nhạc đó, đôi khi nó sẽ giúp để thêm một khối nhỏ trong mã có nội dung "ồ, nhân tiện, tôi đã phải sửa lỗi này và đây là tài liệu tham khảo bugtracker để bạn có thể theo dõi cuộc trò chuyện xung quanh" và trong trường hợp của tôi (khi tôi sử dụng FogBugz) thì nó sẽ như thế này :

//Case: 1234 ~ Throttling based on unusual activity per ABC request.
Throttler myThrottler = new Throttler( oldActivity );

hay bất cứ cái gì. Vì vậy, quan điểm của tôi là một cái gì đó có vẻ không đúng chỗ và không thể đọc được có lẽ là một nơi tốt cho tài liệu nội tuyến. Thu thập kiến ​​thức là một điều đẹp.

Nhưng điểm đầu tiên của tôi là logic kinh doanh của tôi. Tôi thực sự có một khối trong một thủ tục được lưu trữ mà tôi sắp viết lại AM này có một số quy tắc kinh doanh ở phía trước.

/****************************************************************
author  yourstruly
date    2010-11-18
descrip intended use is to blah blah blah
        ended up over actual measured blah blah blah according to blah blah blah
        rules from the customer are:
        If the sum of the blah blah blah is higher than the blah blah blah
        and the blah blah blah contain blah blah blah,
        and the blah blah blah is non-zero,
        recalculate the blah blah blah to fit within the blah blah blah

        Additional rules for us internally: 
        if the blah blah blah originally read blah blah blah don't blah blah blah (set to zero)

        rewritten here with (1) traceable statements for the where clauses.
        If 
            the blah blah blah(1) is higher than the blah blah blah (2)
        and the blah blah blah (3)
        and the blah blah blah is non-zero (9)
        and the blah blah blah is lower than the blah blah blah (4)
        and the edited blah blah blah is higher than the blah blah blah (5)
        then recalculate the blah blah blah (6)
        // See note lower in this document on the math

        If 
            the blah blah blah(1) is higher than the blah blah blah (2)
        and the blah blah blah (3)
        and the blah blah blah is higher than the blah blah blah (7)
        then set the blah blah blah to zero (8)

        (7) dictates the same as (4) but it's easier to do (7)
****************************************************************/

Sorry for the blah blah blah's but proprietary rules and all that ;)

Và thật bất ngờ khi bạn thấy rằng tôi có các yêu cầu (!) Được nhúng trong mã của tôi dưới dạng các nhận xét và tôi có thể tham khảo các nhận xét là /*(1)*/ (mà tôi làm) để điều này có thể dễ dàng theo dõi cho nhân viên tiếp theo (đó là, và anh ta đã có thể tìm thấy những phần cần chỉnh ngay lập tức) và sau đó nếu có ai muốn biết thông số kỹ thuật họ có thể đọc bình luận từ phía trên, và nếu có ai muốn biết mã giả là gì ở đó và nếu bất cứ ai muốn chuyển đổi mã giả thành mã thì bạn đến đó. Đối với tôi điều này dễ đọc hơn nhiều (đối với trường hợp của tôi) vì nó duy trì yêu cầu ban đầu (được lấy từ email) và cho phép dòng suy nghĩ nhanh chóng được tập hợp mà không cần suy nghĩ quá nhiều, và cho phép sử dụng các phép biến đổi dễ dàng của giả thành mã thật.

Và vâng, có một số ý kiến ​​nội tuyến nói rằng như vậy và như vậy không hoạt động như mong đợi trong mã giả vì yêu cầu không hoàn toàn khớp với dữ liệu nên chúng tôi cần Tweak dữ liệu. Nhưng đó là quan điểm của tôi. Chúng tôi đã ghi lại các trường hợp Edge trong dòng và chúng tôi để mã giả trong mã phù hợp để tuân theo logic, vì vậy tất cả chúng tôi đều biết những gì được mong đợi từ các yêu cầu ban đầu

0
jcolebrand