DEV Community

Discussion on: Removing Comments

jfrankcarr profile image
Frank Carr

I'm kind of torn on this issue.

First of all, I like the code itself to be self-documenting with no inline comments. Comments that describe implementation, such as the "stop looping" one you mentioned, can quickly go out of date.

However, in C# components and microservices, I use documentation comments to allow other developers to see Intellisense hints in Visual Studio and to build documentation files using tools like Sandcastle. These comments should describe what the method does, such as "Search for unpaid invoices for specified customer", but not go into any implementation details like "Query XYZ.Invoices database table for unpaid customer invoices".

Also, since I frequently deal with legacy code going back 20+ years in some cases, I want to keep comments made by programmers who left the company many years ago. This gives me insight into what they were thinking when they originally developed the code. I may add my own comments (initialed) to indicate that the comments are no longer applicable if that's the case.

gonedark profile image
Jason McCreary Author • Edited on

Agreed, there is definitely value in widely shared codebase to have a higher level of comments. I would still strive for readable code without comments in any codebase. That is, the comments should augment.