The fuck you of the Ruby/Python worlds

How is this a fuck you? Well written code is self documenting.

— Good, self documenting, well written code is an art and is rather rare, especially with very young (hastily written) or quite old (lots of legacy) codebases.

— Beginners (or low-intermediate users) at a language don't want to read library code. Heck! I don't want to read library code just to figure something out. (I make a point of having a quick “read-over” of the code of every library I use, but in my own time, not on the spot.)

— Code often has a particular structure that one needs to be familiar with in order to understand it. Experience makes this easier, yes (Ruby gems, Rails applications, Python packages, Django installations… all have a general structure, for example), but there's still a lot left to the original programmer. (I have always longed for “code maps” for some large projects, that would essentially show the big picture with annotations of the type “this feature is implemented here and here, and all this code is for BlaBla compatibility, etc,” but I'm getting sidetracked.)

— Finally, code history also has a tendency to make it hard to figure out what code is for. A particular detail might have been put there for a particular edge case, but without context (such as is the case when one is told to “read the code”) it becomes easy to miss.

Good documentation is hard. Good code is hard. Good self-documenting code is extra hard. And generally, it's not the well-designed, well-written methods one will have a problem with. It'll often be with those ‘fuck-you’s of methods. Which is why saying RTFC is so different from saying RTFM.

Putting the onus on devs to write good docs on top of good code for anything that isn't a library with existing traction is stupid because it will never happen.

Until a library has 10x more people using it than writing it, putting work into docs is pretty much time you're putting down the sink, and even then there are largish, well used codebases for which it makes no sense (https://github.com/benhoskings/babushka is a great example).

I tell people to RTFS all the time. I generally link them to the code in question, and specifically often tell them to read the history or look at a specific set of commits. Equating that to a vitriolic fuck you is naieve and honestly, in my opinion a sign of laziness.

Your beginner argument falls on it's ass because noone ever moved on from being a beginner by being spoonfed. I'm not expecting to change your opinion- but I am hoping to at least get you to inspect yours a little more closely.

@richoh well said. Also, for whom is the code written? If you said for the computer/compiler/robots, think again. It is not the machine, but fellow coders that code is written for. It's a human-readable (to as best a degree as it was designed to be at time of conception) document which doubles up as a set of instructions that can be parsed so that the machine can understand them too.

tldr: Though it appears that your computer is parsing and rendering the tags, blocks, indents, loops, classes, allocs you are typing (in Latin alphanumeric glyphs btw), it is actually turning your code into
Base16: {
[3c][21][44][4f][43][54][59][50][45][20][48][54][4d][4c][3e][3c][21][2d][2d][61][6b][61][20][59][4f][55][20][53][54][55][50][49][44][20][43][4f][4d][50][55][54][45][52][2c][20][54][48][49][53][20][49][53][20][48][54][4d][4c][20][54][48][41][54][20][46][4f][4c][4c][4f][57][53][2c][20][4f][4b][41][59][2d][2d][3e][3c][68][74][6d][6c][3e][3c][68][65][61][64][3e][3c][2f][68][65][61][64][3e][3c][62][6f][64][79][3e][3c][70][3e][93][52][65][61][64][20][54][68][65][20][53][6f][75][72][63][65][94][3c][2f][70][3e][3c][2f][62][6f][64][79][3e][3c][2f][68][74][6d][6c][3e] }

Well, see, you tell people to read the source… by pointing them exactly at the right parts of the code and of the relevant commits. Thar's awesome! I'm more referring to a) (standard) library code, and b) generic “read the source” comments, made without referencing as you do. It's a behaviour I equate with someone asking for a specific string function and being given http://www.ruby-doc.org/core-1.9.3/String.html as sole answer (it happens more than one would think). It certainly doesn't seem like something you'd do :)

(Also, rdoc/yard are docs –sorry for the pun– and often, great at that. Even though it's not hand-made, but generated from the code. It's ‘almost code,’ but not quite, abstracting away the details and giving just the API, descriptions, synopsii, and maybe even contextual code. It's still much better than just reading the code, raw.)

You're right on the beginner front. I might not have expressed myself correctly, and I might not have been a beginner long enough to experience too much of it. However I believe ‘moving on [from being a beginner] by not being spoon-fed’ is a bit of an departure from the argument. I can honestly say reading the code of a large application never helped me much in becoming better at programming. Reading and trying out snippets, and reading documentation (and specs! Specs are good for you!), and creating my own stuff, that helped tremendously. I mean, code is what we do, if we weren't reading it… :-/

Generally, I both agree and disagree with you. I agree on the pragmatic front but disagree on the idealist one. At least pardon me for being somewhat of an idealist! :)

To be fair, I do get where the frustration stems from. A lot of todays code conventions, syntax and so on go back to the days of 6 bit processing computers... capable of Boolean arithmetic or for simplicity's sake, a 6 bit (used 6 to keep it simple) CPU would have a maximum positive value of 011 111(bin) = +31 (dec) and negative of 111 111 (bin) = -31 (dec). +/-32bits = buffer overflow. It did then, it does now still. Errors are hardcoded into the "lexicon" :)

I really agree with self documenting code. But that's not all. I don't want to turn into a living debugger and reading every dingle line of code just to learn how to use a library. Most times I don't want to know the internals, just the interface. Imagine you, trying to learn rails, then you got stuck on some part and the only tip you get from experienced programmers is: RTFS. I bet you would lost a day just to find out where the part you are looking for is coded. And this is not just for monumental frameworks like rails; I think tiny libs should be documented as well (they're tiny, won't take too much to get the job done).

Anyway, unless your code is waaaay tiny and self explainable, supply some docs to make user's life less complicated.

@fuadsaud ah, but that's what comments are there for. Rails is maybe not the best of examples, because it's almost ridiculously syntactically designed (and then advertised as the Coding gods' gift to Mankind).
How exactly is require 'Mommy' indent exactly two tabs (LF style line ending)do 'make the world know you are a retard' print "I am retard" ;

And then it didn't work because you are , well a retard.

I like rails, I despise Sinatra. But I don't think ruby or rails have the most self explanatory syntax either - it's almost as if designed to be labyrinthian.