Nhận xét TODO có ý nghĩa? [đóng cửa]

Tôi đang làm việc trên một dự án khá lớn và có nhiệm vụ thực hiện một số bản dịch cho nó. Có hàng tấn nhãn chưa được dịch và trong khi tôi đang tìm hiểu mã, tôi đã tìm thấy đoạn mã nhỏ này

//TODO translations

Điều này khiến tôi suy nghĩ về ý nghĩa của những bình luận này đối với bản thân (và những người khác?) Bởi vì tôi có cảm giác rằng hầu hết các nhà phát triển sau khi họ nhận được một đoạn mã nhất định và đó là điều họ phải làm khi họ không bao giờ nhìn vào điều này cho đến khi họ có để duy trì nó hoặc thêm chức năng mới. Vì vậy, điều này TODOsẽ bị mất trong một thời gian dài.

Liệu nó có ý nghĩa để viết bình luận này hay chúng nên được viết trên bảng trắng / giấy / cái gì khác mà chúng vẫn nằm trong trọng tâm của các nhà phát triển?

Tôi có xu hướng sử dụng // todobình luận cho những việc phải xảy ra, nhưng tôi không thể làm ngay lập tức.

Tôi cũng đảm bảo rằng tôi theo đuổi họ - Tôi tìm kiếm chúng (Visual Studio có một tính năng hay, nơi nó sẽ liệt kê những nhận xét như vậy cho bạn) và đảm bảo rằng mọi việc đã được thực hiện.

Nhưng, như bạn nói, không phải ai cũng siêng năng về chúng và giống như nhiều bình luận, chúng có xu hướng bị thối theo thời gian.

Tôi muốn nói rằng đây là một sở thích cá nhân nhiều hơn - miễn là bạn ghi lại những gì cần phải làm và theo đuổi nó, không thành vấn đề nếu nó nằm trong // todo, ghi chú bài đăng hoặc bảng trắng (nơi họ cũng có thể không bị hành động).

Các IDE hiện đại nhận ra các TODObình luận và chúng hiển thị như vậy trong bảng / cửa sổ / tab riêng của chúng, vì vậy về mặt lý thuyết chúng không bị mất (tôi đang nghĩ Eclipse và Visual Studio, cả hai tôi đều biết đủ để nhớ rằng chúng nhận ra nó).

Bạn thậm chí có thể định cấu hình các từ nhận xét bổ sung như FIXME, BEWAREhoặc bất cứ điều gì bạn muốn tùy chỉnh. Tuy nhiên, các nhà phát triển khác trong dự án của bạn sẽ phải tùy chỉnh IDE của họ theo cùng một cách.

Bây giờ, tôi đã viết "về mặt lý thuyết" bởi vì mặc dù không bị mất, TODO thường không liên quan đến thứ gì đó không cần thiết để ứng dụng hoạt động chính xác "vào lúc này". Và "tại thời điểm này" có thể kéo dài từ 5 phút đến 5 năm, tùy thuộc vào loại / quy mô của dự án :-)

Cuối cùng, theo ý kiến ​​của tôi, vẫn có ý nghĩa hơn khi đưa chúng vào mã, đúng nơi, trả lời chính xác câu hỏi "tôi nên thực hiện thay đổi ở đâu" so với nơi nào khác ngoài mã.

Chỉnh sửa: Vì nó được viết trong bài viết của Wikipedia về các bình luận , bao gồm ngày và chủ sở hữu của TODO được coi là một thông lệ tốt.

Nó có thể có ý nghĩa, ít nhất là đôi khi tôi sử dụng chúng. Điểm mấu chốt là sử dụng các thẻ nhất quán như TODOhoặc FIXMEđể chúng có thể dễ dàng tìm thấy với tìm kiếm văn bản đơn giản.

Ví dụ: các giải pháp "nhanh chóng bẩn" thuận tiện để dán nhãn, đại loại như:

ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable

Nếu mã làm những gì nó phải làm và không ai phàn nàn, thì bình luận đó không có hại. Nếu có thời gian để làm đẹp mã, thật dễ dàng để bắt đầu với việc tìm kiếm FIXMEnhãn.

Trong ngành của tôi, các nhà phát triển được khuyến khích tạo các mục JIRA (hoặc vv) thay vì làm bình luận vì không phải ai cũng có cơ hội để xem các // todomục. Nhưng đôi khi trong các dự án lớn, một thuộc tính tùy chỉnh được xác định dọc theo dòng:

[AttributeUsageAttribute(AttributeTargets.All, AllowMultiple = true)]
public class DeveloperNote : Attribute
{
    public DateTime EntryDate { get; set; }
    public string Description { get; set; }
    public DeveloperNote(int year, int month, int day, string desc)
    {
        EntryDate = new DateTime(year, month, day);
        Description = desc;
    }
}

Và sau đó một phương pháp có thể được trang trí theo cách này ...

[DeveloperNote(2011, 12, 13, "Make the db connection configurable")]

Và những người cao hơn có thể đi cùng và thu hoạch những thứ này một cách tự động. Nó có thể là quá mức cần thiết cho // todolời nhắc đơn giản , nhưng nó hiệu quả. Ngoài ra, nó đòi hỏi một nền tảng .NET.

TODO chỉ là một hình thức con của bình luận. Nhận xét có tiện ích tuyệt vời nếu người viết hoàn toàn có kỹ năng trong việc biết những gì cần truyền đạt và làm thế nào để truyền đạt nó. Một cảm giác hài hước cũng có thể được áp dụng ở đây với liều lượng nhỏ để làm hài lòng những người duy trì nhiều năm sau đó.

Tôi đã nhận được một cuộc gọi vào năm ngoái rằng một số mã của tôi đã bị loại bỏ. Tôi đã rất ấn tượng rằng nó đã được sản xuất và bảo trì trong 16 năm. Vì vậy, hãy lưu ý, mã của bạn có thể tồn tại trong một thời gian dài. Nhận xét về ý định, nhu cầu trong tương lai và có thể đi một chặng đường dài trong việc giúp đỡ ai đó trong nhiều năm kể từ bây giờ, người đang nhìn vào mã của bạn lần đầu tiên.

Theo kinh nghiệm của tôi thì phụ thuộc. Yếu tố chính là liệu nhóm có đủ kỷ luật để theo dõi những bình luận "nhỏ" này hay không. Nếu họ làm thì có, họ có ý nghĩa. Nếu họ không thì những bình luận này chỉ là một sự lãng phí thời gian và bạn có thể muốn xem xét các lựa chọn khác, ví dụ như thẻ câu chuyện.

Cá nhân tôi thỉnh thoảng sử dụng các bình luận TODO nhưng chúng thường chỉ tồn tại trong một thời gian ngắn và tôi thường chỉ có một số lượng rất nhỏ trong số đó như một, hai hoặc ba. Tôi sử dụng chúng như một điểm đánh dấu trong cơ sở mã hơn bất kỳ thứ gì khác. Nếu tôi chờ đợi quá lâu để chăm sóc họ thì tôi sẽ quên đi những gì tôi nghĩ tôi cần 'làm'.

Sở thích của tôi sẽ luôn là không sử dụng những thứ này và thay vào đó sử dụng thẻ câu chuyện hoặc hồ sơ tồn đọng hoặc tương tự. Sử dụng một cơ chế cho một nhiệm vụ.

Tôi đã từng viết chúng trong quá khứ, nhưng tôi đã thấy rằng bạn thường không theo dõi chúng.

Vì vậy, bây giờ tôi chỉ sử dụng chúng để đánh dấu những thứ tôi muốn làm việc ngay sau khi tôi hoàn thành những gì tôi bận rộn. Ví dụ, tôi triển khai một chức năng mới và nhận thấy rằng một chức năng tôi sử dụng có một lỗi nhỏ; Tôi tạo một FIXME để sửa lỗi này để tránh bị trật bánh trong nhiệm vụ hiện tại của mình.

Để giúp tôi, các bản dựng CI của chúng tôi được thiết lập để thất bại nếu có mã FIXME trong mã :-).

Nếu bạn nhận thấy các vấn đề tiềm ẩn không thể giải quyết ngay lập tức, hãy mở một vé / lỗi / vấn đề cho chúng. Bằng cách đó, chúng có thể được ưu tiên như tất cả các lỗi. Tôi cảm thấy điều này tốt hơn nhiều so với việc gặp một số vấn đề trong lỗi DB và một số trong mã là TODO.

Sau đó, bạn có thể đặt TODO với ID lỗi :-).

Tôi nghĩ TODOý kiến, ở một mức độ nào đó, có ý nghĩa. Đặc biệt là nếu bạn đang làm việc lặp đi lặp lại (như là phổ biến trong các cửa hàng nhanh nhẹn và TDD), sẽ có những điều mà bạn nhận được sẽ là cần thiết chẳng bao lâu nhưng mà bạn không muốn làm cho đường vòng để thực hiện ngay sau đó và ở đó.

Điều trở nên xấu xí là khi những bình luận như vậy vẫn còn trong codebase. Mặc dù bạn đang tích cực làm việc với một tính năng, nhưng vẫn tốt để bỏ chúng vào, nhưng ngay khi bạn tiến gần hơn đến việc hoàn thành tính năng, bạn nên tập trung vào việc loại bỏ chúng. Nếu bạn không muốn thực hiện công việc thay thế chúng bằng mã làm việc phù hợp thì ít nhất hãy tính đến chức năng liên quan. Để mượn ví dụ của @ JoonasPulakka, nơi mã ban đầu nói

ConnManager.getConnection("mydatabase"); // FIXME: DB name should be configurable

bạn có thể thay đổi nó thành một cái gì đó như

ConnManager.getConnection(GetDatabaseName());

với, hiện tại, GetDatabaseName () là một sơ khai chỉ đơn giản trả về cùng một chuỗi mà bạn đã bắt đầu. Theo cách đó, có một điểm rõ ràng của việc mở rộng trong tương lai và bạn biết rằng mọi thay đổi được thực hiện sẽ được phản ánh ở bất cứ nơi nào cần tên cơ sở dữ liệu. Nếu tên cơ sở dữ liệu thậm chí là chung chung vừa phải, đây có thể là một cải tiến lớn về khả năng bảo trì.

Cá nhân, tôi sử dụng một từ khóa của riêng tôi thay vì nghiêm ngặt TODO, mặc dù ý định là như nhau: để đánh dấu những thứ mà tôi biết sẽ cần xem lại. Ngoài ra, trước khi tôi kiểm tra mã của mình, tôi thực hiện tìm kiếm mã nguồn toàn cầu cho từ khóa đó, được chọn sao cho thông thường nó không xuất hiện ở bất kỳ đâu trong mã. Nếu nó được tìm thấy, tôi biết tôi đã quên một cái gì đó, và có thể tiếp tục và sửa nó.

Đối với việc bao gồm tên / chữ ký lập trình viên với nhận xét, tôi nghĩ rằng đó là quá mức nếu bạn có một hệ thống kiểm soát phiên bản mã nguồn (bạn có , phải không?). Trong trường hợp đó, tính năng đổ lỗi của nó sẽ cho bạn biết ai đã thêm nhận xét hoặc chính xác hơn là ai đã kiểm tra lần cuối trong một thay đổi đã chạm vào nhận xét đó. Ví dụ, trong Visual Studio, điều này có thể dễ dàng thực hiện bằng cách sử dụng tính năng "Chú thích" được tìm thấy trong số các tính năng kiểm soát nguồn.

Nếu bạn viết TODO hoặc FIXME với ý tưởng rằng người khác sẽ sửa nó khi họ đến mã đó trong một tương lai không xác định thì tôi sẽ nói đừng bận tâm. Họ sẽ xả rác mã và làm lộn xộn phần báo cáo trong IDE của bạn thu thập thông tin này.

Để có ích, họ nên cung cấp một phương tiện để đánh dấu mã của bạn trong tương lai gần (rất) để bạn có thể quay lại trạng thái tâm trí phù hợp nhanh hơn. Nói cách khác, bạn đặt chúng trong mã của bạn chỉ để loại bỏ chúng càng sớm càng tốt.

Bất cứ điều gì sống lâu hơn trong thực tế nên được đặt trong cơ sở lỗi của bạn, nơi nó thuộc về.

Có đủ tiếng ồn trong cuộc sống của chúng ta, chúng ta đừng tạo ra một sự phô trương mới về những thứ gây sự chú ý trong khi nó được yêu cầu ở nơi khác.

2 xu của tôi

Thông thường tôi không thực hiện // TODO bình luận nhưng giữ tất cả chúng trong tệp riêng biệt. Vẫn không thể tìm / ghi phần mềm trực tuyến để dễ dàng quản lý chúng vì vậy các tệp TODO vẫn hữu ích nhất đối với tôi vì khi tôi mở dự án sau một thời gian ngắn tôi quên mất phải làm gì bây giờ và sau đó tôi xem xét tệp TODO và thực hiện công việc . Tôi đã có "filename.cpp 354: Recode this bla bla bla" và nó hữu ích hơn nhiều sau đó tìm kiếm // TODO bình luận trong tệp. Tôi đã làm // TODO Earler khi tôi lười biếng nhưng tôi chỉ xóa những // TODO-s cũ đó khỏi tệp nguồn và không sửa chúng khi dự án hoạt động tốt. Tôi thực sự khuyên bạn nên chuyển tất cả // TODO từ souce sang vị trí riêng biệt và giữ chúng cùng với các todos khác để bạn có thể ưu tiên các nhiệm vụ dễ dàng. Ưu tiên thực sự là điều khó khăn TODO khi bạn có tất cả các TODO của mình trong các tệp khác nhau và các dự án khác nhau.

Tôi nghĩ rằng có tuyệt vời, nhưng không cô đơn. Ví dụ:

//TODO: ADD MY CLICK EVENT LOGIC
throw new Exception();
//Even a simple messageBox could suffice

Cách tiếp cận này hoạt động khá tốt đẹp một cách tiết kiệm. Mặc dù tôi sẽ phải nói rằng biến nó thành thói quen ném ngoại lệ để nhắc nhở bạn hoàn thành một số mã không thực sự là cách tiếp cận chuyên nghiệp nhất. Nhưng nó đã cứu tôi trong một số trường hợp bạn nghĩ rằng bạn đã hoàn thành một cái gì đó và thậm chí viết ra bạn đã hoàn thành khi bạn không có.

Lợi thế rất lớn của việc làm bình luận so với bất kỳ cách nào trong số hàng triệu cách khác mà người ta có thể tạo danh sách nhiệm vụ là việc thực hiện bình luận đi kèm với mã để chúng không bị tách rời.

Có lẽ nơi thích hợp hơn cho những thứ như thế này là trình theo dõi vấn đề thay vì mã.

Tôi thực sự khuyên bạn nên nhập TODO hoặc FIXME vào nhật ký chính thức. Nếu không, chúng có thể dễ dàng tìm kiếm và đó phải là một giai đoạn trong mỗi lần lặp để kiểm tra các TODO và FIXME nổi bật. Những thứ này sau đó có thể được xếp vào mục lục và được thiết lập để khắc phục ngay lập tức hoặc nhóm có thể lên kế hoạch khắc phục chúng vào thời điểm thích hợp.

Cuối cùng, một khi đã sửa, chúng cần được gỡ bỏ - nếu chúng không được loại bỏ một cách có hệ thống sau khi được giải quyết, chúng sẽ mất hiệu quả.

Điểm mấu chốt: Chúng tốt hơn là không đăng nhập các vấn đề, nhưng bạn thực sự phải duy trì chúng.

IntelliJ sẽ thực sự cảnh báo bạn nếu bạn cố gắng cam kết mã có TODO mới. Vì vậy, bạn luôn có thể diễn giải một TODO là "điều này thực sự sẽ xảy ra vào thời điểm tôi cam kết".

Khi bạn coi "TODO" là nhãn ngữ nghĩa cho nhận xét của mình, tôi nghĩ chúng có ý nghĩa.

Trong các tiêu chuẩn mã hóa của công ty tôi, chúng tôi xác định rằng tên viết tắt của nhà phát triển chịu trách nhiệm phải được bao gồm trong TODO ( nghĩa là tôi sẽ gõ "SAA TODO:"). Tôi nghĩ rằng điều này hữu ích, ít nhất là như một quy ước, bởi vì nếu không thì có sự cám dỗ để để lại mã không đạt tiêu chuẩn với ghi chú TODO cho một số nhà phát triển trong tương lai để giải quyết.

Thật hữu ích, nhiều IDE có thể được cấu hình để thêm các nhận xét này vào danh sách tác vụ, cho phép chúng được xử lý tương tự để xây dựng các bản ghi và không bị lãng quên vô thời hạn.

Một phương pháp đáng ghét hơn nhưng hiệu quả hơn có lẽ là biến các bình luận việc cần làm của bạn thành các thông điệp của trình biên dịch, theo cách đó bạn và mọi người khác nhìn thấy nó khi chương trình được biên dịch.

trong Delphi:

{$message 'todo: free this thing when you know its not going to blow up'}

Theo kinh nghiệm của tôi, TODOnên được sử dụng để chỉ ra rằng một đoạn mã không thể sử dụng được và cho người đọc biết những gì cần thiết để làm cho nó có thể sử dụng được (ở địa phương hoặc ở nơi khác).

TODOchú thích không nên được sử dụng để chỉ ra rằng một số đoạn mã sẽ đẹp hơn nếu được sửa đổi theo một cách nào đó. Các ví dụ bao gồm mã bẩn sẽ dễ bảo trì hơn nếu được viết lại hoặc một tính năng bổ sung mà không ai cần. Những chú thích có xu hướng chồng chất và tạo ra grep TODOkết quả vô dụng.