Modularity in programming guides

I’ve read many programming guide books and tutorials. The one thing I’m looking for is, “I want to do X. What is the code I need to write to do just that?”

Many times, the author of the book or tutorial had mixed in other code or concepts into that. I want to know the simplest way to print “Hello World!”. I don’t want to include any extra libraries that don’t help with that. I don’t want any custom functions that makes printing a string any easier. I just want to print a string, ok?

The point is, the author already knows how to accomplish that task you want to learn. It’s when he gets, I don’t know, bored, that he adds other concepts to make it, I don’t know, interesting.

I’m not looking for the least number of code lines to write that accomplishes that task, although it’s usually that. I’m looking for the lines of code that just do what I want.

Because sometimes, I can’t differentiate the important from the extraneous. I don’t know, that’s why I’m learning, remember? This is especially important when I need to mix and match different concepts. If what I learnt has other extra stuff mixed in, then the resulting code has “more” extra stuff.

It’s like I want to mix X and Y, but got (X + dx) and (Y + dy). And I don’t know which parts are dx or dy.

Some authors make it clear which parts are the actual lines of code to accomplish X. Some authors are great at explaining stuff. I’m saying there are many others who don’t or can’t.

So when I wrote my Open XML spreadsheet programming guide, I made sure each chapter was modular. If not, I had sufficient comments and explanations so the reader knows which parts are the important parts. Each chapter was modelled after a major feature/function in the Excel software. How to style text, how to insert images, how to add more worksheets, that kind of thing. The Excel user mixes and matches those functions, so I want the programmer using the guide to be able to do a similar thing.

I got an email from a programmer who bought my guide that he liked to pick apart code to figure it out. I wrote a few custom functions but only because it made the code more readable. The full source code is given, so the reader is free to pick apart those functions and write his own (to better suit his needs).

I believe this is attributed to Albert Einstein:

Make things as simple as possible, but not simpler.

Be careful of encapsulating too much into just one function call.

  1. Dave Doolin

    This is a *really* hard task, finding the correct mix of specificity and abstraction to both solve the problem at hand, while providing an entry point into solving more difficult problems.

    I struggle with it constantly, from both sides.

    Currently, I have a blog post in draft where I’m not even trying to “solve” the problem at hand. It’s simply providing backdrop for the article, which shows people how to solve it for themselves.

  2. Vincent

    I agree it’s a really hard task. The guide I wrote was for Excel, so there were clearly defined tasks. Other times, the problems and tasks aren’t so clear, so it’s up to the author to clarify. Sometimes, after clarification, it’s not as modular as a beginner want or should know.

    Remember that the beginner doesn’t know enough. So he can’t even differentiate whether the solution is modular enough or not.

Comments are closed.