Code Complete

[schwern]

"Code Complete 2" has an entire chapter (#7) on subroutines. Why to make them. How to design them, name them. How long they should be. What parameters they should take. I would highly suggest reading that, even if its just pulling it off the shelf at your local Super Mega Book Store.

But the way I've always thought about subroutines is NOT in terms of reuse. Equating subroutines with reuse is the great downfall of many a new programmer. When you write out your code you often have no idea what is or is not going to be reused. No, subroutines are for something far more important: encapsulation. Limiting what you have to know and how wide an effect a change can have.

In much the same way as a book is broken down into chapters, sections and paragraphs, your code should be broken down into modules, libraries and routines. Why? Because trying to understand a bunch of information smashed together sucks. Subroutines, like paragraphs, let you know where one idea begins and ends. They allow you to skip around within the code. When well named, they allow you to know what the routine does without having to read all the details allowing you to skim.

Routines provide a beginning and an end of scope. Scope for variables. This limits just how much information you need to keep in your head at once. To understand a routine you need to keep in mind A) the variables passed in B) the variables local to the routine C) the (hopefully very few) globals used. When reading a blob of code you have to keep in mind nearly all possible variables because any one could be used at any moment. Since there is no structure any given line of code could manipulate any given piece of data.

Routines also make testing and documentation much, much easier. Its easy to document something that does one thing rather than something that does a dozen. Its also much easier to test. Once you've got a solid foundation of tested routines figuring out what went wrong when you combine them becomes easier. You know the routine works, it must be something about the integration code. Again, limiting the scope of what you need to worry about.

And finally to reuse. Its difficult to know up front what i s and is not going to be reused. Reuse is something which is discovered. When your code is written in one big blob its difficult to see what parts can be made into reusable widgets. Its also a lot of work to extract the reusable bits, especially after they've been hacked on, so you're less likely to redesign a hunk of code into a reusable routine than to just cut & paste. When you write out each logical chunk as a routine as you go the pieces are evident and there for the taking. The borders are well defined so you will be less likely to tangle them up in the course of maintaining the code. The code will then actually get reused.