Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

RTFC is the New RTFM

jakeradakovich.wordpress.com

Post reply on HN
Print view View original

31–40 of 48 posts

Re: RTFC is the New RTFM

#31

Post by sophacles »

spartango wrote: post #18

This worries me a little, because it cuts against the ideas of abstraction that are central to most software engineering. Don't get me wrong, I'm not against reading the code if and when it is available. I just worry that reliance on this MO goes against the idea that you can specify a programming interface for your system and people can develop against that without knowing the implementation. This is rather powerful…

On the other hand, I out of hand reject libraries for which code is not available, unless forced by employers to do otherwise. Documentation is great, but at the end of the day, I still will throw a spike, no matter how good the documentation is. Similarly, I will look at the code to understand how the authors do an abstraction. It isn't to tie my code to something, it is to find out where the abstraction stops working. My applications aren't that special, and not tied to the code, but if I don't understand how something works, I can't wrap my head around how to utilize it properly.

Simply put: I'm going to write my own wrapper for just about any external code anyway - my internal API can then be changed on the backend to use new libraries, rather than changing all my code. I will do this anyway, because rarely is a new library a drop-in replacement for an old library. This, not avoiding an understanding of the code details, is how you keep yourself independent of implementation.

Re: RTFC is the New RTFM

#32

Post by adventureloop »

spartango wrote: post #18

This worries me a little, because it cuts against the ideas of abstraction that are central to most software engineering. Don't get me wrong, I'm not against reading the code if and when it is available. I just worry that reliance on this MO goes against the idea that you can specify a programming interface for your system and people can develop against that without knowing the implementation. This is rather powerful…

I really dislike having to go into source code to figure out basic functionality. This is confounded by the amount of uncommented code. For a lot of the cases one or the other will do. No your shader is not self evident.

Re: RTFC is the New RTFM

#33

Post by duwease »

I've been bitten by open-source AND closed-source applications recently, from different angles.

Once when using an Adobe application that was behaving erratically, and I was unable to see what was happening internally for myself (and obviously the behavior wasn't documented). Incredibly frustrating, and no recourse except to hack around it and hope it didn't mutate.

More recently, I've been bitten by a fairly popular open source application that I intended to use without modification (just configuration). But the documentation was so awful that I couldn't even figure out how to configure it. Ultimately, I had the recourse of stepping through the code to figure it out, but when you're trying to build adoption of your application, it would make sense to make it usable for its main purpose without setting up the actual source code in a debugger.

One interesting generalization I see is that the user-friendliness and documentation of the open-source app correlates quite often to the language used. PHP and Ruby projects seem to be built with an eye towards helping the eventual users use it. The Java projects, while often more competently written and complicated, seem to often be presented as code-only, take it or leave it, user-friendliness be damned.

Re: RTFC is the New RTFM

#34

Post by sixothree »

jerrya wrote: post #9

Yes, projects that claim to be infrastructure and come with no documentation, and presumably few comments, and who knows what unit tests. It would be an exaggeration to refer to that as minimally viable code (mvc). It is really only a statement of the lack of engineering actually being practiced, and makes me wonder about the lack of robustness, the lack of security, the numbers of bugs in the systems produced. I am…

My number one annoyance about many open source projects is that they often don't compile out of the box. I can't even count the number of times I've downloaded a library only to have it fail miserably on compile because of some strange state the author left the source code in, or a library he wrote and failed to include. Etc etc.

Re: RTFC is the New RTFM

#35

Post by sophacles »

eterm wrote: post #26
kaffeinecoma wrote: post #2

I nonchalantly told him to look at the source code of the library we were using. He looked at me like I had asked him to help me dig up a grave. I can't imagine not examining the source code of the various frameworks I use on a daily basis. I think the next time I interview a candidate I will ask them what major open-source libraries they use. Then I will ask them what they think of the quality of the source code, ho…

Wow, I hope you never interview me. FizzBuzz was a filter to filter out people who cannot code. At all. It was never designed as a competency measure, it was designed as a filter, to remove people who are mistaken into believing they can do something they cannot do at all. What you have is a very precise measure, which would not even filter out the BSers who could probably happily talk for five minutes on the merits…

So what would you do if you were unclear on how to do something based on the docs and googling? Have you genuinely never done anything even slightly out of spec with library author's expectations? Do you never need just part of the functionality of a library and wonder what the right way to get it is? Do you always just decide "it's not documented in a way I understand it, time to roll my own"?

Re: RTFC is the New RTFM

#37

Post by jamieb »

frenchy wrote: post #23
kaffeinecoma wrote: post #20

Earlier quoted context omitted.

unless I have a problem the documentation or google doesn't answer Documentation/googling is definitely the right thing to do off the bat. But if they've never had a moment where they had to peek under the hood (or never thought to try, or didn't know how to) then yes, that's my FizzBuzz. I would perhaps not apply this to someone fresh out of school, but I would expect an experienced candidate to know how to "use the…

There is a difference between knowing how to do something and thinking it's a good idea. Obviously if you need to look at your code for pragmatic purposes, that's fine; but if reading third-party code becomes your modus operandi, you just might be using crappy libraries.

I'm using Spring 3.1, Jetty, various OWASP, guava. I am in the code of Spring and Jetty on a daily basis, and OWASP when I first used it. I learned guava by writing unit tests to verify my assumptions - assumptions I learned from the documentation - and which turned out to be mostly wrong.

Documentation is ambiguous, and even document which is unambiguous is often wrong.

Re: RTFC is the New RTFM

#38

Post by drivingmenuts »

kaffeinecoma wrote: post #2

I nonchalantly told him to look at the source code of the library we were using. He looked at me like I had asked him to help me dig up a grave. I can't imagine not examining the source code of the various frameworks I use on a daily basis. I think the next time I interview a candidate I will ask them what major open-source libraries they use. Then I will ask them what they think of the quality of the source code, ho…

Works or doesn't work, does what it says in the docs or doesn't. Those are the only true measures.

Everything else is just opinion.

Re: RTFC is the New RTFM

#39

Post by mtrimpe »

eterm wrote: post #26
kaffeinecoma wrote: post #2

I nonchalantly told him to look at the source code of the library we were using. He looked at me like I had asked him to help me dig up a grave. I can't imagine not examining the source code of the various frameworks I use on a daily basis. I think the next time I interview a candidate I will ask them what major open-source libraries they use. Then I will ask them what they think of the quality of the source code, ho…

Wow, I hope you never interview me. FizzBuzz was a filter to filter out people who cannot code. At all. It was never designed as a competency measure, it was designed as a filter, to remove people who are mistaken into believing they can do something they cannot do at all. What you have is a very precise measure, which would not even filter out the BSers who could probably happily talk for five minutes on the merits…

My most valuable two questions have always been "What part of the stack you're working with do you understand best? Can you explain to me how it works?" and "What is the most complex modification/extension of the stack you've ever done? Can you explain to me how you did it?"

That will show you exactly how well they know their tools, how and how far they bent them to their will, how passionate they are about them and how well they can communicate on difficult technical topics.

I'd be hard-pressed to find other questions that consistently give me that much information about a candidate.

Re: RTFC is the New RTFM

#40

Post by pothibo »

I think thoughtful, detailed guides on how to browse/use code is better than code documentation.

Too often (mostly in interpreted language), I see a method that takes a hash as an option and I see that option being passed down to 3, 4 or more different functions. So in order to know what options are available for a given method, you have to browse through all the other methods that takes the same hash as argument.

I haven't seen a framework dealing with that through documentation. Some are better than others, but they never cover everything.

Post reply on HN