Is leaving comments on code in the past?

Question

When I started my carreer, I was tasked with (correctly) commenting on every module I write. An assignment of what the method does, how its parameters are used, and what to expect in response, etc.

Then, with almost two years, I began to visit outdated codes with misleading and / or useless comments. And in this process, I used them to remove code from the database.

In my recent work, my project manager instructed me not to worry about leaving comments at all, and suggested I rather rely on unit tests to leave the outline of the code I'm writing. I agreed since I tested this code over time, but the comments do not stay up to date, and then it becomes quite misleading.

Recently, I read Martin Fowler's refactoring book to extract a method wherever we see the opportunity to leave some comments. So leaving comments in modules is really an outdated thing now?

Just to summarize: According to my experience, we should not leave comments and, rather, accept the following two options: 1) The extraction method. 2) Unit Test to support module intent.

So, should we always avoid commenting and rely on two options? or do we have other alternatives? Please share your opinion.

Thank you for your interest.

Answer 1

Comments should not be used as a way of relaying how your code works, the code itself, correctly and clearly written, should do this. Instead, comments should be used to describe why you used a particular approach in your code. In this regard, comments can be extremely valuable and, of course, are not a thing of the past.

Answer 2

Comments are also still needed to describe libraries. Of course, you can find out what the function does by studying its source code, but natural language is even easier for people to quickly understand, and you can also omit unnecessary details from the user.

During my studies, I had to work with Eiffel, a very good programming language, but terribly documented. The documentation policy is that the code is self-documenting, and the interfaces are determined by preconditions and postconditions. Of course, you can get reliable data from such restrictions, but they still cannot convey the semantic meaning of the function or its input and output. Consequently, the libraries in Eiffel were extremely difficult to learn, compared, for example, with the heavily documented Java or .NET base classes.

Answer 3

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

Comments that bring nothing are just noise hiding the code, but a simple line here and there, to give the reader some context, is worth the gold.

Answer 4

Well, I personally like to leave comments, especially when in some cases some expressions can lead to some confusion over the next two years if I try to revisit my projects.

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

Answer 5

I assume that the modern approach of the code is to separate (spray) the most possible, therefore the code should be minimized and without comment, therefore not for printing to the human eye. However, code comments (that is, why the encoder did this instead) should be available through some kind of wiki or some kind of relative tool. I think that we will do less and less coding, because we will have some kind of user interfaces that will do this for us. Yes, you say that these user interfaces must be encoded. The other user interfaces I think :)