P. 1
Code Craft the Practice of Writing Excellent Code

Code Craft the Practice of Writing Excellent Code

|Views: 264|Likes:
Published by abdul rasheed shaik

More info:

Published by: abdul rasheed shaik on Sep 29, 2011
Copyright:Attribution Non-commercial

Availability:

Read on Scribd mobile: iPhone, iPad and Android.
download as PDF, TXT or read online from Scribd
See more
See less

10/03/2012

pdf

text

original

19

In this chapter:

Why we need specifications

The types of specifications
we write

What they contain

Why are they ignored?

I’ve never known any trouble that an hour’s reading didn’t
assuage.

—Charles De Secondat

Almost everything worth using is documented.
Your DVD player has an instruction manual. Your
car has a maintenance manual. A contract has
small print. Chocolate cake has a recipe. There are
books and magazines dedicated to practically every
pursuit known to man. If your software is worth
using, it also should be well documented.1
We all know that the carefully tested software
we give to our customers needs to have documen-
tation. Just how much documentation is a moot
point. The user of an office suite certainly thinks
there should be more than the publisher does.
Without a manual to describe the usage mechanics
of your software, whatever form it takes, people
will falsely assume that it can do more than it
wasdesigned to, or use it for purposes no sane
programmer would have ever imagined.

1

Of course, that’s no excuse to craft a bad interface; it must still
be easy and intuitive to use.

368Chapter 19

Developers can just as easily make the same kinds of mistakes during
coding. Just as the final software product needs documentation, so do the
intermediate development steps. This is the sort of documentation that the
end user will (usually) never see. These are the definitions of how the program
will be designed and built. These are the software specifications.
Writing and working with specifications is an important skill of the practic-
ing programmer. Communicating in English (or any other natural language)
is just as important as communicating in code.2

Like eating your vegetables
and exercising regularly, specifications are “good for you” and good for your
software. However, like cabbage and the gym, we avoid them, feel guilty, and
then live to regret the consequences: We end up with unhealthy, flabby
software development.
The traditional notion of a software specification involves a huge wedge
of paper filled with dense text, cryptic tables, and meaningless terminology.
It’s a highly uninspiring prospect: a document that requires more mainte-
nance effort than the code it describes. Developers live in perpetual fear of
being forced to work with the spec.
But it doesn’t have to be this way. Used correctly, specifications oil the
development process. They reduce development risk, help you to work
effectively, and make your life a lot easier. In this chapter, we’ll investigate
the sorts of specifications we need, what should be in them, and why reality
differs so greatly from this ideal.

You're Reading a Free Preview

Download
scribd
/*********** DO NOT ALTER ANYTHING BELOW THIS LINE ! ************/ var s_code=s.t();if(s_code)document.write(s_code)//-->