Is leaving comments on code a thing of past?

Question

When i started my carreer i have been instructed to (properly) comment each and every module that i write. Instructing what a method does, how its parameters are used, and what to expect in return etc.

Then with almost 2years of doing so i started visiting legacy codes with misleading and/or useless comments. And in the process i used to remove them from the code base.

In my recent job my project manager instructed me not to worry about leaving comments at all, and suggested to rather rely on unit tests to leave a blueprint of the code i write. I agreed since i have experienced that code changes with time but comments do not stay up to date, and then it becomes rather misleading.

Then recently i read in Martin Fowler's Refactoring book to extract method wherever we see scope of leaving some comments. So is leaving comments in the modules is really an obsolete thing now?

Just to summarize: As per my experience, we should not leave comments and rather take the following two options: 1) Extract method. 2) Unit Test to support the intent of the module.

So, should we always avoid leaving comments and rely on above two options? or do we have other alternates also? Please share your opinion.

Thanks for your interest.

Answer 1

Comments should not be used as way of relaying how your code works, the code itself, properly and clearly written should do that. Instead, comments should be used to describe why you have taken a particular approach in your code. In this respect comments can be extremely valuable and certainly not a thing of the past.

Answer 2

Well, personally I like leaving comments especially when some cases that some expressions might bring me onto some confusion for the next 2 years if I tried to re-visit my projects.

I think this commenting thing is also useful when doing a game development, algos, etc.

Answer 3

Comments are also still essential to describe libraries. Of course you can derive what a function does by studying its source-code - but natural language is still easier for humans to parse quickly and you can also ommit unnecesary details from the user.

During my studies I had to work with Eiffel, a very good programing language, but horribly documented. The documentation policy is that the code is self-documenting and interfaces are defined by pre- and postconditions. Of course you can derive valid input from such constraints, but they still cannot convey the semantic meaning of a function or its input and output. Hence, the libraries in Eiffel were extremly hard to learn, compared to for instance the heavily documented Java or .NET base classes.

Answer 4

Comments are definitely not a thing of the past, unit tests can only show the user how a function is intended to be used but doesn't describe the reason why the function looks in a certain way. This is especially good when you are refactoring.

Comments that do not bring anything are just noise obscuring the code but a simple line here and there to give the reader some context is gold worth.

Answer 5

I guess modern approach of code consists of separating (atomizing) the more possible, so code should be served minimized and with no comments, so not in a printable way for human-eye. Yet comments of the code (i.e., why coder did this instead of this) should be available through some sort of wiki or some kind of relative tool. I think we are going to do less and less coding because we will have some sort of UIs that will do that for us. Yes, you are going to say that these UIs need to be coded. By others UIs, I think :)