cnews018.doc

经过改进的C语言位操作功能

      -- and makes entries as needed.  At the end of week, he goes
      through the entries and makes a list of the ones that he wants
      to work on, and scratches out those that either he has no time
      for or were really "banana wackers".  

           How did I decide to write PHONENUM?  Recently, I had to
      call Barry, so I had to look up his phone number.  Of course, I
      had Barry's phone number on my computer; but, to look it up, I
      either had to install SideKick or otherwise list it out.  I had
      been meaning to organize them and write up a short program to
      display a phone number.  (Everyone knows someone, possibly even
      themselves, who keeps meaning to write a short little program to
      do something and keeps putting it off, right?)  So, I decided I
      would finally sit down and write this program and that I would
      use it to show the steps involved in developing a program from
      start to finish.  

           Once you decide that it's time to act on one of these
      ideas, what do you do? 

      The Solution        
      (Oops, let's be formal -- "Defining the Solution".) 

           Hey, the solution is simple, you say?  All I have to do is
      write a program look up a phone number.  Correct, but that's not
      all that goes into the solution.  How do I want it displayed?
      What should the program look like when it's running?  Do I want
      windows?  As you can see, there are a number of things which go
      into the solution of a programming problem.  

           Well, in the case of this program, PHONENUM, what do "I"
      want?  (See, this is the advantage of being the author, I can
      write the program exactly as I want it.)  I want to be able to
      call the program with a name as an argument on the command
      line.  Why?  I have a program which will display the location of
      area codes throughout the country that way, in addition to one
      that will display the location of local telephone exchanges, so
      why not one to display phone numbers of the people I deal with? 



      


      Issue                        C News                            20


           Basically, that's all that there is to the solution of this
      problem.  I want to be able to type: 

           PHONENUM lynch

      at the system prompt and have Barry's phone number displayed.  

           Wait a minute, how am I going to add phone numbers to the
      list I will be using?  Sure, I could maintain a text file with a
      text editor or even add a text editor into the program to
      maintain the list.  Okay, so I will have to have a way to add
      names and numbers to my list.  

           I guess, why I am at it, that I also need to have a warning
      displayed to the user if the wrong number of parameters is
      entered.  ("I" won't forget, but what if some else wants to use
      the finished program?) 

           There are a number of other things I could include in the
      finished program, many of which will be revealed as you read
      this article, but these three are the only ones necessary for
      the basic program.  (I am purposely making this program fairly
      basic, feel free to make modifications as you see fit.) 

      To recap, the solution to this problem contains the following
      parts: 

           Command-line interface.
           Warning for in correct number of parameters.
           Method to add names to the list.

      Mapping the Solution       
      (Also known by the dreaded term "flowchart".) 

           Okay, I know this section brings up the dreaded F-word.
      Come on, let's say it and get it over with.  Flowchart.  There,
      that wasn't too bad, was it? (You know, in this case, I like the
      textbook types term, "mapping the solution".) 

           As most people may have guessed, I don't particularly care
      for doing flowcharts.  Back when I was learning FORTRAN, I used
      to do the flowcharts after I had finished the program and i
      would not have done them if I had not been required to turn them
      in.  These days, however, I do find that mapping out the
      solution is a good idea.  I don't always map out the solution,
      because there are some programs that are straightforward and
      don't need it.  There are also times I only map out a part of a
      solution (normally, a more complex part).  

           One other thing I don't do anymore, is worry about what
      symbols I use.  Obviously, if I was preparing this as part of a
      class assignment or something, I would; but, for my own


      


      Issue                        C News                            21


      programs, boxes are all the symbols I need.  

      First, let's see an example of an unnecessary flowchart: 

                              +---------+
                              |  BEGIN  |
                              +---------+
                                   |
                                   |
                                   |
                         +--------------------+
                         |                    |
                         |      Display       |
                         |  "Hello, world."   |
                         |                    |
                         +--------------------+
                                   |
                                   |
                                   |
                              +---------+
                              |   END   |
                              +---------+

      Obviously, in the case of PHONENUM, our flowchart will be a
      little more complex.  The flowchart is rather self explanatory,
      and is contained in the accompanying file, PHONENUM.CHT.  (This
      way, if you don't want to look at it, you don't have to, just
      continue on to the next section.) 

      Coding the Program       
      (It's about time!!) 

           Well, we're finally to the point where we can begin coding
      the program.  Normally, this would be the section where you give
      serious consideration to the language you are going to use; but,
      since this is the C NEWS, we're going to do it in C.  

           Since this is not an article on how to write C programs, I
      am not going to go into depth about writing the code.  (If you
      are new to C, see Wayne's articles elsewhere in this issue,
      which will explain how to code in C.) 

           PHONENUM.C is written in TurboC, version 2.0, although it
      should compile with just about any C compiler with few
      modifications.  

           It is not the most elegant solution to our original
      problem, but it does work.  Why didn't I write a slick,
      whiz-bang piece of code?  For two reasons, one because I am just
      trying to illustrate the steps involved in program design, and
      because it gives us something to do in future articles, where we
      will enhance and refine the program.  (Future articles?  That's


      


      Issue                        C News                            22


      why "Part 1" included in the title.) 

      Debugging the Program       
      (Okay, I'll admit I don't write perfect programs the first time,
      but I'm not alone.) 

           Let's face it, we all make mistakes.  (That's why someone
      invented debuggers.)  When you first compile a program, you're
      going to find some mistakes.  Some will be little, such as a
      missing "}", while others will be harder to figure out.  While
      debuggers will solve a lot of problems, especially when it comes
      to missing "}"s, there are a lot of things they won't tell you.
      Among the hardest mistakes to find are mistakes in logic.  

           I find that once I have corrected syntax and pointer
      problems, that running different sets of test data will find
      errors.  In the case of our PHONENUM, looking up names that are
      not there, adding names and then looking them up, etc.  

           Once you have found all the errors you can find and then
      corrected them, it's time to beta test the program.  Someone
      other than yourself, may find problems you overlooked.  

           Well, there is a fairly large bug in PHONENUM.C (What,
      published code with a bug in it?!)  Can you find it?  Whoever
      mails me the best solution to this bug, by 01 May 1990, will get
      a free C NEWS coffee mug.  If more than one person sends in the
      same solution, a name will be selected out of a hat.  (In order
      to make it fair for our foreign readers, whose letters will take
      longer to reach us.)  All solutions must be sent through the
      mail, to: 

           Jim Singleton
           P. O. Box 15314
           Arlington, VA  22215

      No electronic replies, whether in the C Echo, GEnie, etc. will
      be eligible.  

      Documenting the Program       
      (Oh no, the dreaded "D" word!) 

           One of the most neglected parts of programming, if not the
      most neglected part, is adequately documenting the program. (I
      know, you'd rather be writing code.)  Adequate documentation is
      also one of the most important parts of programming, which is
      why it seems strange that it is so often neglected. Perhaps it
      is because most programmers would rather just program, rather
      than "waste" time documenting the program. (Hey, didn't I
      already say this?)  Failure to provide proper documentation is
      one of the worst habits a programmer can fall into.  



      


      Issue                        C News                            23


      Proper documentation consists of three parts: 

           1)  the program listing,
           2)  the technical manual, and
           3)  the user's manual.

      All three of these parts are important and none should be
      neglected.  

           The program listing is just that -- a listing of the
      program (which is why we call it a program listing).  This
      listing should include all the modules, sub-programs, etc. which
      make up the program.  Everything in the listing should be well
      commented.  Many programmers have a tendency to comment their
      programs rather sparsely, if at all, often because they add the
      comments after the program has been completed. The comments
      should be included as the program is being written.  This
      increases the actual time spent coding in the program, but it
      saves time later (trust me).  It is important to remember, that
      each time the program is updated, the comments should be
      updated.  (If you have ever had to update a piece of uncommented
      code, years later, you realize how important it is to add
      comments.) You don't have to comment each and every line of
      code, just what would not be self explanatory to someone else
      reading your code.  (Such things as 

           int count;

           or

           count++;

      are self-explanatory.) 

           The technical manual should describe the functions and
      purposes for each part of the program.  It serves as a detailed
      description of the program and how the program operates.  The
      technical manual should be written so that it will be useful
      should the program ever have to be modified or updated.  If the
      programmer prepared a flow chart prior to coding, each part of
      the flow chart could serve as a separate section of the
      technical manual.  The technical manual should contain the
      information the programmer used when the program was designed
      and coded.  Often, the technical manual will be what you have
      written down while you have been working on a program (my loose
      leaf notebook or Barry's notebook).  

           Lastly, the users manual describes the operation of the
      program from the perspective of the user.  This is what most
      programmers consider, along with comments embedded in the
      program, to be documentation.  While this is often the only part
      of the documentation which the programmer prepares, it is often


      


      Issue                        C News                            24


      of rather poor quality.  The user's manual should guide the user
      through the operation of the program, describing how it works
      and what is required of the user.  It should also include sample
      sessions or examples, whichever is more appropriate, of the
      program in operation.  As the user will refer to the users
      manual to learn how to use the program, in the case of problems,
      and with questions concerning the capabilities of the program,
      the users manual should anticipate as many potential questions
      and problem areas as possible and address them.  

           Why spend the time documenting a program?  If the program
      is for use by others, good documentation can prevent a lot of
      questions as to why something doesn't work.  If the program
      needs to be updated at a future date, good documentation makes
      the process a lot easier, whether you do it yourself or have
      some one else do it.  It can get very frustrating trying to
      figure out how a program without comments is supposed to
      operate.  What if it is only a short program, a utility composed
      of only a few lines of code, does it still need all three parts
      of the documentation?  Of course it does.  The technical and
      user's manuals may only be a page or so in length, but the
      documentation serves the same purpose as it would for a longer
      program--it tells how the program operates, how it was written,
      why it was written, how to use it, and what each part of the
      code does.  Proper documentation, a habit for every good
      programmer.  

           Okay, so what does the documentation for PHONENUM look
      like? Well, the code is commented, that's one-third of the
      documentation out of the way.  The technical documentation is
      what was written in my notebook (which is essentially in this
      article) and the flowchart.  Since this program was written for
      my own use, there really isn't any need for a users manual.
      However, if I were to distribute this program to anyone, I would
      write up a short READ.ME file, which would explain how it
      works.  

      Updating the Program.       

           After you have been using a program for a while, certain
      improvements will need to be made, parameters may change, etc.
      There may even be an error in the program that escaped detection
      earlier.  Updating the program is actually a never ending
      process, unless the program is either very simple or intended
      for limited use.  This is where the time spent commenting the
      code and writing the documentation comes in handy, because you
      won't be spending all your time trying to figure out what each
      line of code is supposed to do.  

           Since we just finished PHONENUM, there really isn't
      anything to do in the way of updating it, right?  Well....  When
      I was writing PHONENUM, I began to think of ways to make it more


      


      Issue                        C News                            25