a guest Oct 15th, 2012 17,853 Never
Not a member of Pastebin yet? Sign Up, it unlocks many cool features!
  1. Merc Release 2.1
  2. Sunday 01 August 1993
  4. Furey
  5. Hatchet
  6. Kahn
  10. === 'I'm running a Mud so I can learn C programming!'
  12. Yeah, right.
  14. The purpose of this document is to record some of our knowledge, experience and
  15. philosophy.  No matter what your level, we hope that this document will help
  16. you become a better software engineer.
  18. Remember that engineering is work, and NO document will substitute for your
  19. own thinking, learning and experimentation.
  23. === How to Learn in the First Place
  25. (1) Play with something.
  26. (2) Read the documentation on it.
  27. (3) Play with it some more.
  28. (4) Read documentation again.
  29. (5) Play with it some more.
  30. (6) Read documentation again.
  31. (7) Play with it some more.
  32. (8) Read documentation again.
  33. (9) Get the idea?
  35. The idea is that your mind can accept only so much 'new data' in a single
  36. session.  Playing with something doesn't introduce very much new data, but it
  37. does transform data in your head from the 'new' category to the 'familiar'
  38. category.  Reading documentation doesn't make anything 'familiar', but it
  39. refills your 'new' hopper.
  41. Most people, if they even read documentation in the first place, never return
  42. to it.  They come to a certain minimum level of proficiency and then never
  43. learn any more.  But modern operating systems, languages, networks, and even
  44. applications simply cannot be learned in a single session.  You have to work
  45. through the two-step learning cycle MANY times to master it.
  49. === The Environment
  51. Computer: the big or little box that you're using to run Merc.  Computers come
  52.     from a _manufacturer_ and have a _model_ name.  Here is a list of common
  53.     manufacturers and models that you're likely to encounter:
  55.         Manufacturer    Model
  56.         ------------    -----
  58.         Sun             Sun-2
  59.         Sun             Sun-3
  60.         Sun             Sun-4
  61.         DEC             Vax 5000
  62.         DEC             Vax 5900
  63.         IBM             RS/6000
  64.         NeXT            NextCube
  65.         Sequent         Symmetry
  66.         Sequent         Balance
  68.     As far as hardware goes, Merc will run on any 32-bit hardware.
  70. Operating system: the lowest level program running on your computer.  Most
  71.     common computers run Unix or some variant of it, such as SunOS, Ultrix,
  72.     AIX, Mach, or Dynix.  Notice that many of these variants end in 'IX'.
  74.     The two major 'families' of Unix are Berkeley Unix (developed at the
  75.     illustrious University of California, Berkeley) and System 5 Unix
  76.     (developed by Bell Laboratories, the progenitors of Unix).
  78.     The most common non-Unix operating system is VMS (a proprietary operating
  79.     system from DEC for their VAX computers).  In the personal computer world,
  80.     you'll find MS-DOS, OS/2 for IBM PC's and compatibles, and MacOS for Apple
  81.     Macintosh'es.
  83.     GET THIS STRAIGHT: 'VAX' IS NOT AN OPERATING SYSTEM.  It's the name of a
  84.     family of computers from DEC.  There are plenty of Vax'es running VMS, and
  85.     there are even more Vax'es running Berkeley Unix or Ultrix.  The Vax'es
  86.     running Unix have a lot more in common with other machines running
  87.     Unix than they have with Vax'es running VMS.
  89.     As far as operating systems go, Merc will run on Unix or Unix variants with
  90.     TCP/IP networking compatible with Berkeley Unix.  It will also run, in
  91.     single-user mode only, on MS-DOS.  With a reasonable amount of work, Merc
  92.     can be ported to any operating system that provides TCP service for telnet
  93.     connections.
  95. Languages: Merc is written in C.  ANSI (the American National Standards
  96.     Institute) has a specification for the C language, and Merc is written in
  97.     Ansi Standard C.
  99.     The most popular compiler for Ansi Standard C is the Gnu 'gcc' compiler
  100.     produced by the Free Software Foundation.  It's available by anonymous
  101.     ftp from  Merc compiles just fine with Gcc 1.38, so
  102.     you can probably use 1.42 and skip the much larger 2.X versions.
  104.     You don't have to use gcc.  IBM RS/6000's running the AIX operating system
  105.     come with an Ansi C compiler already.  So do NeXT machines (the standard
  106.     'cc' on NeXT happens to be the Gnu C compiler).  Any Ansi compiler will
  107.     work.
  109.     Unfortunately, there are still many machines out there without an Ansi
  110.     standard C compiler.  (Sun is the worst offender in this regard).  You
  111.     can attempt to compile Merc with a non-Ansi (traditional) C compiler by
  112.     using the 'mktrad' script.  See trad.txt for details.
  114. If you don't know what the manufacturer and model of your computer is, as well
  115. as its operating system, and whether the C compiler is Ansi or non-Ansi, then
  116. you need to find out.
  120. === Basic Unix Tools
  122. 'man'   -- gives you online manual pages
  124. 'grep'  -- stands for 'global regular expression print'
  126. 'vi'
  127. 'emacs'
  128. 'jove'  -- use whatever editor floats your boat
  129.            but learn the hell out of it
  130.            you should know EVERY command in your editor
  132. 'ctags' -- makes 'tags' for your editor
  133.            allows you to goto functions by name in any source file
  135. '>'
  136. '>>'
  137. '<'
  138. '|'     -- input and output redirection
  139.            get someone to show you, or dig it out of 'man csh'
  141. These are the basic day-in day-out development tools.  Developing without
  142. knowing how to use ALL of these well is like driving a car without knowing how
  143. to change gears.
  147. === Debugging: Theory
  149. Debugging is a science.  You formulate a hypothesis, make predictions based on
  150. the hypothesis, run the program and provide it experimental input, observe its
  151. behavior, and confirm or refute the hypothesis.
  153. A good hypothesis is one which makes surprising predictions which then come
  154. true; predictions that other hypotheses don't make.
  156. The first step in debugging is not to write bugs in the first place.  This
  157. sounds obvious, but sadly, is all too often ignored.
  159. If you build a program, and you get ANY errors or ANY warnings, you should fix
  160. them before continuing.  C was designed so that many buggy ways of writing code
  161. are legal, but will draw warnings from a suitably smart compiler (such as 'gcc'
  162. with the '-Wall' flag enabled).  It takes only minutes to check your warnings
  163. and to fix the code that generates them, but it takes hours to find bugs
  164. otherwise.
  166. 'Desk checking' (proof reading) is almost a lost art in 1993.  Too bad.  You
  167. should desk check your code before even compiling it, and desk-check it again
  168. periodically to keep it fresh in mind and find new errors.  If you have someone
  169. in your group whose ONLY job it is to desk-check other people's code, that
  170. person will find and fix more bugs than everyone else combined.
  172. One can desk-check several hundred lines of code per hour.  A top-flight
  173. software engineer will write, roughly, 99% accurate code on the first pass,
  174. which still means one bug per hundred lines.  And you are not top flight.
  175. So ... you will find several bugs per hour by desk checking.  This is a very
  176. rapid bug fixing technique.  Compare that to all the hours you spend screwing
  177. around with broken programs trying to find ONE bug at a time.
  179. The next technique beyond desk-checking is the time-honored technique of
  180. inserting 'print' statements into the code, and then watching the logged
  181. values.  Within Merc code, you can call 'printf' or 'fprintf' to dump
  182. interesting values at interesting times.  Where and when to dump these values
  183. is an art, which you will learn only with practice.
  185. If you don't already know how to redirect output in your operating system, now
  186. is the time to learn.  On Unix, type the command 'man csh', and read the part
  187. about the '>' operator.  You should also learn the difference between
  188. 'standard output' (e.g. output from 'printf') and 'error output' (e.g. output
  189. from 'fprintf').
  191. Ultimately, you cannot fix a program unless you understand how it's operating
  192. in the first place.  Powerful debugging tools will help you collect data, but
  193. they can't interpret it, and they can't fix the underlying problems.  Only you
  194. can do that.
  196. When you find a bug ... your first impulse will be to change the code, kill the
  197. manifestation of the bug, and declare it fixed.  Not so fast!  The bug you
  198. observe is often just the symptom of a deeper bug.  You should keep pursuing
  199. the bug, all the way down.  You should grok the bug and cherish it in fullness
  200. before causing its discorporation.
  202. Also, when finding a bug, ask yourself two questions: 'what design and
  203. programming habits led to the introduction of the bug in the first place?'
  204. And: 'what habits would systematically prevent the introduction of bugs like
  205. this?'
  209. === Debugging: Tools
  211. When a Unix process accesses an invalid memory location, or (more rarely)
  212. executes an illegal instruction, or (even more rarely) something else goes
  213. wrong, the Unix operating system takes control.  The process is incapable of
  214. further execution and must be killed.  Before killing the process, however, the
  215. operating system does something for you: it opens a file named 'core' and
  216. writes the entire data space of the process into it.
  218. Thus, 'dumping core' is not a cause of problems, or even an effect of problems.
  219. It's something the operating system does to help you find fatal problems which
  220. have rendered your process unable to continue.
  222. One reads a 'core' file with a debugger.  The two most popular debuggers on
  223. Unix are 'adb' and 'gdb', although occasionally one finds 'dbx'.  Typically
  224. one starts a debugger like this: 'adb merc' or 'gdb merc core'.
  226. The first thing, and often the only thing, you need to do inside the debugger
  227. is take a stack trace.   In 'adb', the command for this is '$c'.  In gdb,
  228. the command is 'backtrace'.  The stack trace will tell you what function your
  229. program was in when it crashed, and what functions were calling it.  The
  230. debugger will also list the arguments to these functions.  Interpreting these
  231. arguments, and using more advanced debugger features, requires a fair amount of
  232. knowledge about assembly language programming.
  234. If you have access to a program named 'Purify' ... learn how to use it.
  238. === Profiling
  240. Here is how to profile a program:
  242. (1) Remove all the .o files and the 'merc' executable:
  244.         rm *.o 'merc'
  246. (2) Edit your makefile, and change the PROF= line:
  248.         PROF    = -p
  250. (3) Remake merc:
  252.         make
  254. (4) Run merc as usual.  Shutdown the game with shutdown when you have run long
  255.     enough to get a good profiling base.  If you crash the game, or kill the
  256.     process externally, you won't get profiling information.
  258. (5) Run the 'prof' command:
  260.         prof merc > prof.out
  262. (6) Read prof.out.  Run 'man prof' to understand the format of the output.
  264. For advanced profiling, you can use 'PROF = -pg' in step (2), and use the
  265. 'gprof' command in step 5.  The 'gprof' form of profiling gives you a report
  266. which lists exactly how many times any function calls any other function.  This
  267. information is valuable for debugging as well as performance analysis.
  269. Availability of 'prof' and 'gprof' varies from system to system.  Almost every
  270. Unix system has 'prof'.  Only some systems have 'gprof'.
  274. === Schedule versus Features versus Quality
  276. Now for a few words on project management.
  278. Sooner or later, almost any project faces a trade-off between schedule,
  279. features, and quality.  Consider a student writing a term paper on the last
  280. night.  He has three unpalatable choices: he can turn it in late (miss the
  281. schedule).  He can turn in a shorter paper that doesn't cover everything
  282. (reduce the features).  Or he can churn out gibberish (lower the quality).
  284. Similarly in a software project, one often has a choice between making the
  285. release date, or dropping features, or shipping everything on time and
  286. hoping that it works (it usually doesn't).
  288. The most important thing to realize about this decision is that it IS a
  289. decision.  One can't get out of it by hoping that some miracle will occur.
  290. If you don't react consciously, then external circumstances will drive the
  291. decision.
  293. Ok, so suppose you are faced with the trade-off and go for a schedule slip.
  294. Don't take a small slip ... take a big impressive slip.  If you say
  295. 'I'll just fix this one problem and finish ASAP', then likely you will
  296. wish you had taken just a little more time later.  If you say 'I think I
  297. need another day, so I'll slip by a week', then it's much more likely
  298. that what you'll have at the end of the week will do the job.  It's better
  299. to slip a large block of time once then to slip day-by-day or hour-by-hour
  300. repeatedly.
  302. If you go for dropping features, again, carve off a big hunk.  Don't be
  303. timid and pretend that you're going to do that work 'if you just get a
  304. little spare time.'  That feature of your project is GONE, exploit the
  305. lessened requirements for all the savings you can!
  307. I can't offer much advise on how to reduce quality, because that's always
  308. my last choice for what to drop on a project.
  312. === Sleeping
  314. Simple and obvious, but true ... engineering takes an alert mind.
  316. It's very easy, very seductive, to throw a lot of consecutive hours at a
  317. problem.  One can get into a 'flow' state where one's mind becomes filled
  318. with the problem, and the work just pours out, hour after hour.  Many
  319. writers report that they watch a story take place, and just transcribe
  320. what they see, pounding out page after page of text.  Many software
  321. engineers have experienced a similar feeling, where the code appears
  322. to arise spontaneously as they watch themselves type.
  324. I believe most real work gets done in this state.
  326. My experience, however, is that the 'flow' period can end subtly and
  327. gradually.  Without ever noticing a change, I notice that new work isn't
  328. flowing out of my hands anymore, that I'm spending lots of time fixing
  329. up mistakes I made just a few moments ago.  Instead of ideas flashing
  330. confidently through my mind, doubts and questions arise.
  332. At this point there is a temptation to throw some more hours at the problem.
  333. 'I'm here, and I was getting a lot of work done, why don't I just stay all
  334. night until I figure this out?'  This is a trap!  Don't do it!
  336. Instead, I suggest: go home, eat, shower, sleep, put yourself back together
  337. again.  Resume the next day.  While you sleep, your mind will work on the
  338. problem anyways, and you'll probably wake up with new ideas.  You'll get
  339. more done between 10:00 am and 2:00 pm the next day, then if you stayed up
  340. between midnight and 10:00 am.
  342. There is a problem with this strategy: remotivating yourself in the morning.
  343. If the project is one of your choice, that's usually not a problem.  If it's
  344. something you have to do but don't enjoy, you have to balance the remotivation
  345. problem versus the very low productivity of working without sleep.
  349. === Books for Serious Programmers
  351. Out of all the thousands of books out there, three stand out:
  353. Kernighan and Plaugher, _The Elements of Programming Style_.
  355. Kernighan and Ritchie, _The C Programming Language_.
  357. Brooks, _The Mythical Man Month_
RAW Paste Data
We use cookies for various purposes including analytics. By continuing to use Pastebin, you agree to our use of cookies as described in the Cookies Policy. OK, I Understand