You have probably been reading agile books. The agile style seems to be small functions that do one thing and are well named. In fact within a function if you have to write a comment, many of the agile books advise taking that code, wrapping it in a function with an understandable name which can serve as that comment and calling that. One of the reasons is that they are big into DRY (don't repeat yourself) and comments often have a habit of becoming outdated and repeating stuff that should be clear from the code. The only guaranteed documentation is the code.
But in most real code bases, I often see functions that do multiple things or are poorly named. E.g. request_ait, hoa_request_ait... I have no clue what those functions do. The abbreviations hoa and ait might mean something to your business, but what if someone new comes in? I would say a comment could clear up what is being done (most new people are just thrown into the fire without much formal business training). Many times the acronyms in programs do not tie to common business acronyms. E.g. instead of FindSpellingErrorInList someone decided to do FSE_List or something. Good luck to someone who does not know that FSE is how you find a spelling error in a list unless there is a comment.
Another thing is the language itself. For example Java can document error conditions by throwing well named exception (throws ArgumentOutOfRangeException, throws NoMoreAITSlotsFreeException, etc.). But even then some functions throw runtime exceptions which do not need to be declared and are not obvious. Something like that can benefit from a comment. If you move on to C where errors are often passed by setting errno or returning some type of return value out of the normal range...comments become VERY useful. But if you are going to comment there needs to be stuff in place to keep them up to date, and out of date comments need to be treated as a bug and with the same seriousness as keeping the codebase updated.
Also when using a library in something like Java/Perl often it is much easier just to go through the javadoc/POD [perl documentation format] to read the function names/variable names and a brief description of what they do rather than to go through the code interpreting what is done... I know in both Java and .NET that I do not go through the library source code when I want to use them, I go through the Java Docs/MSDN and that makes me much more productive... Reading the code it is harder to jump file to file from function to function when reading the code. In JavaDocs/MSDN it is really easy to click on the hyper links to jump through the documentation from one function to another.
Additionally comments are the only way to communicate why something is so. The code only communicates what is happening and how it is done (although some declarative languages do not even communicate the how). For the why it requires some other document. E.g. do you need to fire some hardware operations on a device before doing a certain hardware operation? If you do not comment, another developer may look and say hmmm why is this guy/girl doing operation x and then y when they should only be doing y. If you do not document that y does not work unless you do x first with a comment the developer has no way of knowing.
So basically it's a trade off (like most things in software)...... For a function comment the most important things that spring to mind:
- Are your functions well named with names that clearly reveal what they do? If not, this would seem to indicate comments YAY
- Do your functions mostly do one thing? If not this would seem to indicate comments....
- Are there a lot of implicit error conditions, weird out of range return values, numeric error codes (e.g. C errno)? If you answered yes, this would seem to indicate comments
- Do your functions have many side effects, especially to global structures? If so then comments are your friend.....
- Is everyone interested in readable code or does the quality of the code base vary based on who works on something? If it varies then comments might be your friend, you don't want to see RLAB
And there are many more things besides those 3. For example, named modules, named classes, named structs, etc. all create a context. If you have a customer class and an attribute called name, then you know that is a customer name. If you just have a variable in the middle of nowhere called name, how do you know if it is a CustomerName, SupplierName, PetName?
To summarize, the most important concern is clearly communicating your intend in the code. If the code does not do that, and you cannot refactor and enforce keeping the code like that then comments are necessary.
That being said, you just moved to this company so you probably will have to conform with the Javadocs whether they are right or wrong.