That wad my impression too. If it does the latter, then it's certainly worth having in the library.

basically, yes. but importantly the data is always the last parameter, so that you can build and compose functions in a point free style (ie, deferring thinking about or mentioning the data).

so:

this convention makes the library more powerful and elegant than underscore or lodash.

So, in effect, you would turn JS into a list processing language?

What about the lazy evaluations? If I feed it a collection, will it evaluate each index one-by-one, or generate a monster O(n^n) loop?

what in god's name are you talking about?

I think he's misunderstanding chaining functions together

Bank 1 sucks so we get a new account at Bank 2. We request an ACH for $5k from bank 1 to bank 2. Money leaves bank 1, no money arrives at bank 2. Bank 1: "well the money's gone, its stuck in bank 2's system". Bank 2: "well we don't have the money, its bank 1's fault". How does this even happen in a financial system?? HTTP at least gives you error codes. Been going on for 8 days and 4 different contacts and google says this is not an isolated incident in the least. lol.

I am so ****ing bored. It's my last week, they have no work for me to do at all. I wrote the beginning of a react app to replace a very aged Tcl/Tk desktop app I made many years ago. Kind of losing interest in it though. Worked on my CAM software some, ditto. Seems rude to watch movies or play games in sight of people working.

They'd like me to take my vacation, obv, but **** that?

Write a check next time?

I dunno banking well, let alone business banking if that's what this is aboot

Time to make sure those tech docs are in top notch condition for those who will work on your stuff later.
It's a great opportunity to leave a good impression for future references.

And the technical docs are usually lackluster if your place is anything like 99% of the other places out there.

There are no tech docs. We have a very pitiful wiki that contains nothing at all about the work I do. I call the wiki "the place information goes to die", there is literally not a single page on it that isn't out of date by the time it's complete, if it ever is.

The code I wrote is mostly very simple and self-explanatory, and I really focused on making the developer API extremely consistent and easy to use. In the beginning the nice exterior housed an extremely ugly interior (some of it is still ugly) under the theory that once you take control over your API and make the exterior good, you can gradually change the interior to suit it.

I'm not done with that and probably no one else cares so I doubt it'll get worked on.

An example of some of the bull**** I inherited is: there is a crucial data structure that is populated both from a mysql table and a mongo collection. One is layered over the top of the other. It is to weep.

Oh and for the last job I left, I wrote meticulous documentation, that clearly no one ever looked at again, ever. I consulted for them many times over the years since, and no one had ever seen it, or could produce it. It was a complete waste of my time. I presented it to at least 10 people in a meeting before I left, which made absolutely no difference.

meh. What else are you going to do? The last place I left I took the time to comment out a bunch of the crap I wrote, and then took the time to say "this other crap was here when I got here and I don't really know what it does if anything, here be dragons".

do some online training? like, learn a new language/framework or something. then it looks like you are doing work, and you are actually helping yourself out.

I learned React/Redux in the last week, and basically taught myself javascript. Not that it's likely to be useful to me.

The only documentation I've found that people actually read is a) a setup guide for new devs to get up to speed (because they have to get up to speed somehow) and b) the readme files on github or stash or w/e. So I try to put anything I need to document in one of those two places.

Otherwise I just blow it off because you're exactly right - no one ever reads that stuff - your boss just wants it so he can check some box in some process validation document that no one ever reads or follows either.

some day i'd really like to collect info on and categorize the various levels of programming skills and material appropriate for moving to the next level.

for example:

beginner level 1 - can write 'hello world', rec. reading: any intro tutorial
beginner level 3 - can write basic sql statements, make small pet projects with multiple classes, understands basic data structures, rec. reading: some language agnostic book

and so on. Maybe something like this already exists somewhere. If not, I imagine it'd be useful, as it gets really easy during the learning process to feel like you're not sure what to learn next.

reading stuff like this makes me think i won't be able to work anywhere

Partially true, but a big reason is also because 99% of tech docs are horribly written and way out of date with the code its supposed to document.

@Rusty: If you think that 500 lines of comments spread along your code is a substitute for documentation I challenge you to think again.

Several libraries/systems that I have produced are still in use many years down the road. To a big part because I take care of writing excellent documentation.

I talked to my uni prof last year. The discrete event simulation framework that I have built over 12 years ago was still being used by current master students as starting point for various simulators they write.
The code I produced was not that great as far as I can recall, but people can pick it up, spend an hour or two on documentation and make it their own.

A by product of the waterfall process. Specify requirements, design, code, and test in that order pretty much guarantees your documentation is out of date. The horribly written part comes about pretty much because there is little upside for developers in doing a good job of tech writing.

Agree with you. Comments get obsolete and keeping them current requires a level of effort. Mostly they aren't that helpful. Sometimes they are though.

What characterizes excellent documentation in your view?

Cool.

I will consider it excellent almost by default if it covers these points:
Relevance - it is roughly as up to date as the code itself
Operation - from how to install, changing setup up to day-by-day (or run-by-run) operation
Structure - these are the parts that make the software tick; input, output clarified
Reference - what do classes, methods, structures, et al. do? My code has thrown an exception / ended with an error... why, and more importantly, how do I recover/resume?

Optional:
Appendix - search and find main classes, methods, etc by name; point to where in the documentation those are mentioned. A regular search will yield the same results obv. But for some people, this is extremely helpful in seeing how "core" the thing is they're looking at.

Other minor things that can have a huge positive impact are stuff like explicitly pointing out where weak points may be. E.g.: being absolutely clear where heuristics were used instead of algorithms and why and how often this is expected to get it wrong.
Another bonus is where development has stopped - what was next on the to-do or nice-to-have list that was not included?

This sounds like a lot and, yes, it is.
But no need to overdo it for trivial parts. If you wrote a custom add() method, there is no need to go into too much detail other than stating this input leads to that output.
If it is trivial, it is trivial. No need to bloat the docs.

Have you ever seen the Programmer Competency matrix?

http://sijinjoseph.com/programmer-competency-matrix/

First hit with a Google search but can't remember if it's the same one I saw years ago.

Sent from my SM-G900R4 using Tapatalk

I care about one thing more than any of the above, even:

The docs should start with concrete examples of the 2-5 most common use cases (or just 1, if that's enough).

If you do that, you can **** up almost everything else and it probably won't matter to me unless I end up needing some obscure part of your API. If you don't do that, it doesn't make a difference how thorough and up to date your docs are, because you probably just wasted a minimum of 15 minutes of my time, and often way more.

Example of good: https://github.com/request/request

Very top: example of making request to google in a few lines (80% of people never have to read beyond that)
Bonus: Good documentation on all the more obscure features below that, should I need them.

That's part of the operation section. In your example of an API or library that would indeed be enough if it is only going to be consumed.

My example above is about code that someone else will have to work on or extend later.

ah i see.

Have to admit, this makes my heart swell: