Most of us have at least heard of the Grimm Fairy Tales. The Brothers Grimm travelled through Germany compiling folk tales, which they published into an excellent collection of myths (pattern-conveying stories) that convey simple lessons to us at any age.
Today, we'll look at the story of Clever Elsa.
Elsa was a serving girl who
If it hasn't happened to you yet, it will:
You're working with library code - say, GNUTLS. You've dug around and installed all the prerequesites, and the libraries are all set up. You're all ready to get to work...
But the documentation doesn't match the headers you have. It turns out that all the documentation matches
Programmers are not unlike Dory from Finding Nemo, in that we have a limited memory. It seems like every time we sit down to code, and we are randomly struck by a lightning bolt of inspiration, we immediately lose it when we notice something shiny.
That's an extreme example, sure, but programmers do have a
Encapsulation is a key aspect of the Object Oriented Programming model, and for good reason. We have an easier time grasping units which do one thing than hundreds of independent operations and objects that can do a number of things. While C does not contain the class descriptor found in C++ or Java, we
When you commit to a set of documentation, you are telling all the users how your code will work and how they should use it. This has a trickle-down effect, such that any changes to the documented features can destroy entire suites of programs.
Violation of the Rule
Suppose you provide documentation for an early-release form
Generally, I don't much care for IDEs. In my experience, IDEs add increasingly specific features to maintain their relevance, resulting in bloated software which takes too many resources to accomplish a relatively simple task.
However, as functions get more complex, it becomes increasingly difficult to make your code match the original prototypes. This is where
Ask any programmer what the most irritating part of programming is, and they'll either say debugging or documentation. Admittedly, I am one of the rare exceptions (I dislike the coding part most, because it's less about solving a problem than it is translating the solution), but I have a standard which removes the most
If I hand you a black box with one unlabeled button, what do you think that box can do? How do you think the box works?
Unfortunately, programs are essentially black boxes. Unless you have either written or read the entire source code, you can't really know how the system is supposed to work.