I voted yes, but it really depends on WHAT you are writing for code.

If you're writing internal functions nobody else is going to use, the code should be documenting itself -- in that way the same goes for comments. Smart coding reduces the need for comments, smart coding and smart commenting reduces the need for external documentation.

But if you're writing an API or library OTHER developers are going to use, or a tailored system for a client who may end up having other people work with it in the future, DAMNED STRAIGHT YOU DOCUMENT IT!

Goes back to another of those lessons I learned in the 1980's -- if you can't document it, you probably shouldn't have written it.

You write a function or method that other people are going to use, OF COURSE you have to document it. What it gets passed for parameters, what it can return for values... that's just common sense. EVEN if the function name and variables presented in the code are verbose, if it's a library, framework, or API it's not like everyone who is going to use it is going to dive headlong into the codebase to find each and every function they can use!

That said, you document CALLS, parameters, and what's returned... you don't go ape-shit documenting what each and every line of code does anymore than you would waste time commenting each and every blasted line.

Hence why every time I see derpitude like this:

return $result; // and now we're done

I have to choke back the urge to deliver a pimp-slap.

Depends on the project and the audience.

One thing I've learned over the years (but have yet to master) is that at some point, I won't be at my current job and somebody else will need to pick up where I left off. Providing sufficient (not necessarily extensive, but sufficient) documentation is key to me not getting phone calls or emails for several months. I'm not talking about code documentation, per se, but documenting my job, what I do, where things are located on the network, what processes happen, who to contact when things fail, etc.

For code documentation, if the project is public, that is, for other developers, such as an API, then absolutely extensive documentation is necessary. If the project is internal, then maybe not so much.

I also believe in user guides, but I leave writing those to someone else more suited to that task.

I think anything excess is too much to process and understand. For instance, when I look at AWS docs, I am usually confused, because there is so much that you need a documentation for the documentation, documentation-ception, if you will. :P

Documentation should be concise and to the point, nothing more and nothing less, IMHO. My fav piece of documentation is from my favorite Javascript module - lodash. Very concise.

Yes, I do. The reason why is because I am a "how things work" kind of a person and as a reverse engineer and foreward engineer, I'm having to figure codebases out all the time. The one's without documentation can be a real pain and waste a lot of time. I don't get how someone can spend a year or two writing a massive application and then have absolutely no documentation about it... It baffles my mind. And I say that coming from the perspective of actually *enjoying* turning assembly language into higher level languages or just analyzing assembly and machine code directly. Even though I love reverse engineering and I am never given a documentation for malware from the malware authors, I still believe that code up in a repository online and especially code developed professionally should have a documentation.

I sort of agree with the concept of "the code should be self-documenting" but the reality is that most of the time, the code is not self-documented well enough to completely avoid a documentation and having a full documentation which is also indexed and displayed properly can save a lot of precious time for a library user. Another argument for this in a professional codebase is, what happens when the devs quit or move on who made the original codebase and nobody knows how it works? This is another reason for docs. Docs, docs, docs!

The more documentation you have, the more you have to maintain.

so letting the documentation be generated from the code and be minimal seams a more feasible solution to me.

but than .... I'm lazy ;D....