3 ms·

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 r

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 in working with other people, complex systems, and systems that are changing, where reading the code may become inefficient. I'd push back on the mindset of RTFC by saying that as a developers we should try not to link ourselves to infrastructure for which RTFM fails. I know it biases my search for libraries. > I realize complaining about the lack of documentation in some open source projects is like complaining that there is no foie gras at a friend’s free dinner party I'd argue that docs aren't foie gras, and not having them is like having a compile error/obvious segfault in your code. Just like stability, docs matter.

dllthomas 13y ago
I agree with you. There should be solid documentation. However, there will always be corner cases, and occasionally it can be worthwhile/necessary to dig in and figure it out, and the ability to do so can be a big win. Though one must be appropriately wary about relying on undocumented behavior.
sophacles 13y ago
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.
adventureloop 13y ago
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.
hamburglar 13y ago
The main problem with RTFC is that it tells you nothing about how the code is supposed to behave, which is important. Yes, I can see, by looking at the source, how this version of this code behaves, but unless I have an interface spec or some documentation, I have no idea whether this behavior is intended or not, and therefore I have no idea whether the behavior is something I can count on in v.next. This is one reason my current project uses a whole stable of ruby gems that we are absolutely terrified of ever upgrading: all we know about their behavior is what we can observe about one specific version of the source.

dllthomas 13y ago

I agree with you. There should be solid documentation. However, there will always be corner cases, and occasionally it can be worthwhile/necessary to dig in and figure it out, and the ability to do so can be a big win. Though one must be appropriately wary about relying on undocumented behavior.

sophacles 13y ago

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.

adventureloop 13y ago

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.

hamburglar 13y ago

The main problem with RTFC is that it tells you nothing about how the code is supposed to behave, which is important. Yes, I can see, by looking at the source, how this version of this code behaves, but unless I have an interface spec or some documentation, I have no idea whether this behavior is intended or not, and therefore I have no idea whether the behavior is something I can count on in v.next. This is one reason my current project uses a whole stable of ruby gems that we are absolutely terrified of ever upgrading: all we know about their behavior is what we can observe about one specific version of the source.