├── C++ Coding Standards.html
├── how_to_be_a_programmer.html
└── how_to_be_a_programmer.md


/how_to_be_a_programmer.md:
--------------------------------------------------------------------------------
   1 | # How to be a Programmer: A Short, Comprehensive, and Personal Summary
   2 | 
   3 | ### Robert L Read
   4 | 
   5 | Copyright Š 2002, 2003 Robert L. Read
   6 | 
   7 | Copyright
   8 | 
   9 | Copyright Š 2002, 2003
  10 | 
  11 | by Robert L. Read. Permission is granted to copy, distribute and/or modify
  12 | this document under the terms of the GNU Free Documentation License, Version
  13 | 1.2 or any later version published by the Free Software Foundation; with one
  14 | Invariant Section being 'History (As of February, 2003)', no Front-Cover
  15 | Texts, and one Back-Cover Text: 'The original version of this document was
  16 | written by Robert L. Read without renumeration and dedicated to the
  17 | programmers of Hire.com.' A copy of the license is included in the section
  18 | entitled 'GNU Free Documentation License'.
  19 | 
  20 | 2002
  21 | 
  22 | * * *
  23 | 
  24 | ## Dedication
  25 | 
  26 | To the programmers of Hire.com.
  27 | 
  28 | **Table of Contents**
  29 | 
  30 | 1. Introduction
  31 | 
  32 |     
  33 | 
  34 | 2. Beginner
  35 | 
  36 |     
  37 | 
  38 | Personal Skills
  39 | 
  40 |     
  41 | 
  42 | Learn to Debug
  43 | 
  44 | How to Debug by Splitting the Problem Space
  45 | 
  46 | How to Remove an Error
  47 | 
  48 | How to Debug Using a Log
  49 | 
  50 | How to Understand Performance Problems
  51 | 
  52 | How to Fix Performance Problems
  53 | 
  54 | How to Optimize Loops
  55 | 
  56 | How to Deal with I/O Expense
  57 | 
  58 | How to Manage Memory
  59 | 
  60 | How to Deal with Intermittent Bugs
  61 | 
  62 | How to Learn Design Skills
  63 | 
  64 | How to Conduct Experiments
  65 | 
  66 | Team Skills
  67 | 
  68 |     
  69 | 
  70 | Why Estimation is Important
  71 | 
  72 | How to Estimate Programming Time
  73 | 
  74 | How to Find Out Information
  75 | 
  76 | How to Utilize People as Information Sources
  77 | 
  78 | How to Document Wisely
  79 | 
  80 | How to Work with Poor Code
  81 | 
  82 | How to Use Source Code Control
  83 | 
  84 | How to Unit Test
  85 | 
  86 | Take Breaks when Stumped
  87 | 
  88 | How to Recognize When to Go Home
  89 | 
  90 | How to Deal with Difficult People
  91 | 
  92 | 3. Intermediate
  93 | 
  94 |     
  95 | 
  96 | Personal Skills
  97 | 
  98 |     
  99 | 
 100 | How to Stay Motivated
 101 | 
 102 | How to be Widely Trusted
 103 | 
 104 | How to Tradeoff Time vs. Space
 105 | 
 106 | How to Stress Test
 107 | 
 108 | How to Balance Brevity and Abstraction
 109 | 
 110 | How to Learn New Skills
 111 | 
 112 | Learn to Type
 113 | 
 114 | How to Do Integration Testing
 115 | 
 116 | Communication Languages
 117 | 
 118 | Heavy Tools
 119 | 
 120 | How to analyze data
 121 | 
 122 | Team Skills
 123 | 
 124 |     
 125 | 
 126 | How to Manage Development Time
 127 | 
 128 | How to Manage Third-Party Software Risks
 129 | 
 130 | How to Manage Consultants
 131 | 
 132 | How to Communicate the Right Amount
 133 | 
 134 | How to Disagree Honestly and Get Away with It
 135 | 
 136 | Judgement
 137 | 
 138 |     
 139 | 
 140 | How to Tradeoff Quality Against Development Time
 141 | 
 142 | How to Manage Software System Dependence
 143 | 
 144 | How to Decide if Software is Too Immature
 145 | 
 146 | How to Make a Buy vs. Build Decision
 147 | 
 148 | How to Grow Professionally
 149 | 
 150 | How to Evaluate Interviewees
 151 | 
 152 | How to Know When to Apply Fancy Computer Science
 153 | 
 154 | How to Talk to Non-Engineers
 155 | 
 156 | 4. Advanced
 157 | 
 158 |     
 159 | 
 160 | Technological Judgment
 161 | 
 162 |     
 163 | 
 164 | How to Tell the Hard From the Impossible
 165 | 
 166 | How to Utilize Embedded Languages
 167 | 
 168 | Choosing Languages
 169 | 
 170 | Compromising Wisely
 171 | 
 172 |     
 173 | 
 174 | How to Fight Schedule Pressure
 175 | 
 176 | How to Understand the User
 177 | 
 178 | How to Get a Promotion
 179 | 
 180 | Serving Your Team
 181 | 
 182 |     
 183 | 
 184 | How to Develop Talent
 185 | 
 186 | How to Choose What to Work On
 187 | 
 188 | How to Get the Most From Your Teammates
 189 | 
 190 | How to Divide Problems Up
 191 | 
 192 | How to Handle Boring Tasks
 193 | 
 194 | How to Gather Support for a Project
 195 | 
 196 | How to Grow a System
 197 | 
 198 | How to Communicate Well
 199 | 
 200 | How to Tell People Things They Don't Want to Hear
 201 | 
 202 | How to Deal with Managerial Myths
 203 | 
 204 | How to Deal with Organizational Chaos
 205 | 
 206 | Glossary
 207 | 
 208 | A.
 209 | 
 210 | B. History (As Of February, 2003)
 211 | 
 212 | C. GNU Free Documentation License
 213 | 
 214 |     
 215 | 
 216 | PREAMBLE
 217 | 
 218 | APPLICABILITY AND DEFINITIONS
 219 | 
 220 | VERBATIM COPYING
 221 | 
 222 | COPYING IN QUANTITY
 223 | 
 224 | MODIFICATIONS
 225 | 
 226 | COMBINING DOCUMENTS
 227 | 
 228 | COLLECTIONS OF DOCUMENTS
 229 | 
 230 | AGGREGATION WITH INDEPENDENT WORKS
 231 | 
 232 | TRANSLATION
 233 | 
 234 | TERMINATION
 235 | 
 236 | FUTURE REVISIONS OF THIS LICENSE
 237 | 
 238 | ADDENDUM: How to use this License for your documents
 239 | 
 240 | ## Chapter 1. Introduction
 241 | 
 242 | **Table of Contents**
 243 | 
 244 | To be a good programmer is difficult and noble. The hardest part of making
 245 | real a collective vision of a software project is dealing with one's coworkers
 246 | and customers. Writing computer programs is important and takes great
 247 | intelligence and skill. But it is really child's play compared to everything
 248 | else that a good programmer must do to make a software system that succeeds
 249 | for both the customer and myriad colleagues for whom she is partially
 250 | responsible. In this essay I attempt to summarize as concisely as possible
 251 | those things that I wish someone had explained to me when I was twenty-one.
 252 | 
 253 | This is very subjective and, therefore, this essay is doomed to be personal
 254 | and somewhat opinionated. I confine myself to problems that a programmer is
 255 | very likely to have to face in her work. Many of these problems and their
 256 | solutions are so general to the human condition that I will probably seem
 257 | preachy. I hope in spite of this that this essay will be useful.
 258 | 
 259 | Computer programming is taught in courses. The excellent books: _The Pragmatic
 260 | Programmer_ [Prag99], _Code Complete_ [CodeC93], _Rapid Development_ [RDev96],
 261 | and _Extreme Programming Explained_ [XP99] all teach computer programming and
 262 | the larger issues of being a good programmer. The essays of Paul
 263 | Graham[PGSite] and Eric Raymond[Hacker] should certainly be read before or
 264 | along with this article. This essay differs from those excellent works by
 265 | emphasizing social problems and comprehensively summarizing the entire set of
 266 | necessary skills as I see them.
 267 | 
 268 | In this essay the term _boss_ to refer to whomever gives you projects to do. I
 269 | use the words _business_, _company_, and _tribe_, synonymously except that
 270 | business connotes moneymaking, company connotes the modern workplace and tribe
 271 | is generally the people you share loyalty with.
 272 | 
 273 | Welcome to the tribe.
 274 | 
 275 | ## Chapter 2. Beginner
 276 | 
 277 | **Table of Contents**
 278 | 
 279 | Personal Skills
 280 | 
 281 |     
 282 | 
 283 | Learn to Debug
 284 | 
 285 | How to Debug by Splitting the Problem Space
 286 | 
 287 | How to Remove an Error
 288 | 
 289 | How to Debug Using a Log
 290 | 
 291 | How to Understand Performance Problems
 292 | 
 293 | How to Fix Performance Problems
 294 | 
 295 | How to Optimize Loops
 296 | 
 297 | How to Deal with I/O Expense
 298 | 
 299 | How to Manage Memory
 300 | 
 301 | How to Deal with Intermittent Bugs
 302 | 
 303 | How to Learn Design Skills
 304 | 
 305 | How to Conduct Experiments
 306 | 
 307 | Team Skills
 308 | 
 309 |     
 310 | 
 311 | Why Estimation is Important
 312 | 
 313 | How to Estimate Programming Time
 314 | 
 315 | How to Find Out Information
 316 | 
 317 | How to Utilize People as Information Sources
 318 | 
 319 | How to Document Wisely
 320 | 
 321 | How to Work with Poor Code
 322 | 
 323 | How to Use Source Code Control
 324 | 
 325 | How to Unit Test
 326 | 
 327 | Take Breaks when Stumped
 328 | 
 329 | How to Recognize When to Go Home
 330 | 
 331 | How to Deal with Difficult People
 332 | 
 333 | ## Personal Skills
 334 | 
 335 | ### Learn to Debug
 336 | 
 337 | Debugging is the cornerstone of being a programmer. The first meaning of the
 338 | verb _to debug_ is to remove errors, but the meaning that really matters is _
 339 | to see into the execution of a program by examining it_. A programmer that
 340 | cannot debug effectively is blind.
 341 | 
 342 | Idealists that think design, or analysis, or complexity theory, or whatnot,
 343 | are more fundamental are not working programmers. The working programmer does
 344 | not live in an ideal world. Even if you are perfect, your are surrounded by
 345 | and must interact with code written by major software companies, organizations
 346 | like GNU, and your colleagues. Most of this code is imperfect and imperfectly
 347 | documented. Without the ability to gain visibility into the execution of this
 348 | code the slightest bump will throw you permanently. Often this visibility can
 349 | only be gained by experimentation, that is, debugging.
 350 | 
 351 | Debugging is about the running of programs, not programs themselves. If you
 352 | buy something from a major software company, you usually don't get to see the
 353 | program. But there will still arise places where the code does not conform to
 354 | the documentation (crashing your entire machine is a common and spectacular
 355 | example), or where the documentation is mute. More commonly, you create an
 356 | error, examine the code you wrote and have no clue how the error can be
 357 | occurring. Inevitably, this means some assumption you are making is not quite
 358 | correct, or some condition arises that you did not anticipate. Sometimes the
 359 | magic trick of staring into the source code works. When it doesn't, you must
 360 | debug.
 361 | 
 362 | To get visibility into the execution of a program you must be able to execute
 363 | the code and observe something about it. Sometimes this is visible, like what
 364 | is being displayed on a screen, or the delay between two events. In many other
 365 | cases, it involves things that are not meant to be visible, like the state of
 366 | some variables inside the code, which lines of code are actually being
 367 | executed, or whether certain assertions hold across a complicated data
 368 | structure. These hidden things must be revealed.
 369 | 
 370 | The common ways of looking into the 'innards' of an executing program can be
 371 | categorized as:
 372 | 
 373 |   * Using a debugging tool, 
 374 | 
 375 |   * Printlining --- Making a temporary modification to the program, typically adding lines that print information out, and 
 376 | 
 377 |   * Logging --- Creating a permanent window into the programs execution in the form of a log.
 378 | 
 379 | Debugging tools are wonderful when they are stable and available, but the
 380 | printlining and logging are even more important. Debugging tools often lag
 381 | behind language development, so at any point in time they may not be
 382 | available. In addition, because the debugging tool may subtly change the way
 383 | the program executes it may not always be practical. Finally, there are some
 384 | kinds of debugging, such as checking an assertion against a large data
 385 | structure, that require writing code and changing the execution of the
 386 | program. It is good to know how to use debugging tools when they are stable,
 387 | but it is critical to be able to employ the other two methods.
 388 | 
 389 | Some beginners fear debugging when it requires modifying code. This is
 390 | understandable---it is a little like exploratory surgery. But you have to
 391 | learn to poke at the code and make it jump; you have to learn to experiment on
 392 | it, and understand that nothing that you temporarily do to it will make it
 393 | worse. If you feel this fear, seek out a mentor---we lose a lot of good
 394 | programmers at the delicate onset of their learning to this fear.
 395 | 
 396 | ### How to Debug by Splitting the Problem Space
 397 | 
 398 | Debugging is fun, because it begins with a mystery. You think it should do
 399 | something, but instead it does something else. It is not always quite so
 400 | simple---any examples I can give will be contrived compared to what sometimes
 401 | happens in practice. Debugging requires creativity and ingenuity. If there is
 402 | a single key to debugging is to use the _ divide and conquer_ technique on the
 403 | mystery.
 404 | 
 405 | Suppose, for example, you created a program that should do ten things in a
 406 | sequence. When you run it, it crashes. Since you didn't program it to crash,
 407 | you now have a mystery. When out look at the output, you see that the first
 408 | seven things in the sequence were run successfully. The last three are not
 409 | visible from the output, so now your mystery is smaller: 'It crashed on thing
 410 | #8, #9, or #10.'
 411 | 
 412 | Can you design an experiment to see which thing it crashed on? Sure. You can
 413 | use a debugger or we can add printline statements (or the equivalent in
 414 | whatever language you are working in) after #8 and #9. When we run it again,
 415 | our mystery will be smaller, such as 'It crashed on thing #9.' I find that
 416 | bearing in mind exactly what the mystery is at any point in time helps keep
 417 | one focused. When several people are working together under pressure on a
 418 | problem it is easy to forget what the most important mystery is.
 419 | 
 420 | The key to divide and conquer as a debugging technique is the same as it is
 421 | for algorithm design: as long as you do a good job splitting the mystery in
 422 | the middle, you won't have to split it too many times, and you will be
 423 | debugging quickly. But what is the middle of a mystery? There is where true
 424 | creativity and experience comes in.
 425 | 
 426 | To a true beginner, the space of all possible errors looks like every line in
 427 | the source code. You don't have the vision you will later develop to see the
 428 | other dimensions of the program, such as the space of executed lines, the data
 429 | structure, the memory management, the interaction with foreign code, the code
 430 | that is risky, and the code that is simple. For the experience programmer,
 431 | these other dimensions form an imperfect but very useful mental model of all
 432 | the things that can go wrong. Having that mental model is what helps one find
 433 | the middle of the mystery effectively.
 434 | 
 435 | Once you have evenly subdivided the space of all that can go wrong, you must
 436 | try to decide in which space the error lies. In the simple case where the
 437 | mystery is: 'Which single unknown line makes my program crash?', you can ask
 438 | yourself: 'Is the unknown line executed before or after this line that I judge
 439 | to be executed in the about the middle of the running program?' Usually you
 440 | will not be so lucky as to know that the error exists in a single line, or
 441 | even a single block. Often the mystery will be more like: 'Either there is a
 442 | pointer in that graph that points to the wrong node, or my algorithm that adds
 443 | up the variables in that graph doesn't work.' In that case you may have to
 444 | write a small program to check that the pointers in the graph are all correct
 445 | in order to decide which part of the subdivided mystery can be eliminated.
 446 | 
 447 | ### How to Remove an Error
 448 | 
 449 | I've intentionally separated the act of examining a program's execution from
 450 | the act of fixing an error. But of course, _ debugging_ does also mean
 451 | removing the bug. Ideally you will have perfect understanding of the code and
 452 | will reach an 'A-Ha!' moment where you perfectly see the error and how to fix
 453 | it. But since your program will often use insufficiently documented systems
 454 | into which you have no visibility, this is not always possible. In other cases
 455 | the code is so complicated that your understanding cannot be perfect.
 456 | 
 457 | In fixing a bug, you want to make the smallest change that fixes the bug. You
 458 | may see other things that need improvement; but don't fix those at the same
 459 | time. Attempt to employ the scientific method of changing one thing and only
 460 | one thing at a time. The best process for this is to be able to easily
 461 | reproduce the bug, then put your fix in place, and then rerun the program and
 462 | observe that the bug no longer exists. Of course, sometimes more than one line
 463 | must be changed, but you should still conceptually apply a single atomic
 464 | change to fix the bug.
 465 | 
 466 | Sometimes, there are really several bugs that look like one. It is up to you
 467 | to define the bugs and fix them one at a time. Sometimes it is unclear what
 468 | the program should do or what the original author intended. In this case, you
 469 | must exercise your experience and judgment and assign your own meaning to the
 470 | code. Decide what it should do, and comment it or clarify it in some way and
 471 | then make the code conform to your meaning. This is an intermediate or
 472 | advanced skill that is sometimes harder than writing the original function in
 473 | the first place, but the real world is often messy. You may have to fix a
 474 | system you cannot rewrite.
 475 | 
 476 | ### How to Debug Using a Log
 477 | 
 478 | _ Logging_ is the practice of writing a system so that it produces a sequence
 479 | of informative records, called a _ log_. _ Printlining_ is just producing a
 480 | simple, usually temporary, log. Absolute beginners must understand and use
 481 | logs because their knowledge of the programming is limited; system architects
 482 | must understand and use logs because of the complexity of the system. The
 483 | amount of information that is provided by the log should be configurable,
 484 | ideally while the program is running. In general, logs offer three basic
 485 | advantages:
 486 | 
 487 |   * Logs can provide useful information about bugs that are hard to reproduce (such as those that occur in the production environment but that cannot be reproduced in the test environment). 
 488 | 
 489 |   * Logs can provide statistics and data relevant to performance, such as the time passing between statements. 
 490 | 
 491 |   * When configurable, logs allow general information to be captured in order to debug unanticipated specific problems without having to modify and/or redeploy the code just to deal with those specific problems. 
 492 | 
 493 | The amount to output into the log is always a compromise between information
 494 | and brevity. Too much information makes the log expensive and produces _
 495 | scroll blindness_, making it hard to find the information you need. Too little
 496 | information and it may not contain what you need. For this reason, making what
 497 | is output configurable is very useful. Typically, each record in the log will
 498 | identify its position in the source code, the thread that executed it if
 499 | applicable, the precise time of execution, and, commonly, an additional useful
 500 | piece of information, such as the value of some variable, the amount of free
 501 | memory, the number of data objects, etc. These log statements are sprinkled
 502 | throughout the source code but are particularly at major functionality points
 503 | and around risky code. Each statement can be assigned a level and will only
 504 | output a record if the system is currently configured to output that level.
 505 | You should design the log statements to address problems that you anticipate.
 506 | Anticipate the need to measure performance.
 507 | 
 508 | If you have a permanent log, printlining can now be done in terms of the log
 509 | records, and some of the debugging statements will probably be permanently
 510 | added to the logging system.
 511 | 
 512 | ### How to Understand Performance Problems
 513 | 
 514 | Learning to understand the performance of a running system is unavoidable for
 515 | the same reason that learning debugging is. Even if the code you understand
 516 | perfectly precisely the cost of the code you write, your code will make calls
 517 | into other software systems that you have little control over or visibility
 518 | into. However, in practice performance problems are a little different and a
 519 | little easier than debugging in general.
 520 | 
 521 | Suppose that you or your customers consider a system or a subsystem to be too
 522 | slow. Before you try to make it faster, you must build a mental model of why
 523 | it is slow. To do this you can use a profiling tool or a good log to figure
 524 | out where the time or other resources are really being spent. There is a
 525 | famous dictum that 90% of the time will be spent in 10% of the code. I would
 526 | add to that the importance of input/output expense (I/O) to performance
 527 | issues. Often most of the time is spent in I/O in one way or another. Finding
 528 | the expensive I/O and the expensive 10% of the code is a good first step to
 529 | building your mental model.
 530 | 
 531 | There are many dimensions to the performance of a computer system, and many
 532 | resources consumed. The first resource to measure is _ wall--clock time_, the
 533 | total time that passes for the computation. Logging wall-clock time is
 534 | particularly valuable because it can inform about unpredictable circumstance
 535 | that arise in situations where other profiling is impractical. However, this
 536 | may not always represent the whole picture. Sometimes something that takes a
 537 | little longer but doesn't burn up so many processor seconds will be much
 538 | better in computing environment you actually have to deal with. Similarly,
 539 | memory, network bandwidth, database or other server accesses may, in the end,
 540 | be far more expensive than processor seconds.
 541 | 
 542 | Contention for shared resources that are synchronized can cause deadlock and
 543 | starvation. Deadlock is the inability to proceed because of improper
 544 | synchronization or resource demands. Starvation is the failure to schedule a
 545 | component properly. If it can be at all anticipated, it is best to have a way
 546 | of measuring this contention from the start of your project. Even if this
 547 | contention does not occur, it is very helpful to be able to assert that with
 548 | confidence.
 549 | 
 550 | ### How to Fix Performance Problems
 551 | 
 552 | Most software projects can be made with relatively little effort 10 to 100
 553 | times faster than they are at the they are first released. Under time-to-
 554 | market pressure, it is both wise and effective to choose a solution that gets
 555 | the job done simply and quickly, but less efficiently than some other
 556 | solution. However, performance is a part of usability, and often it must
 557 | eventually be considered more carefully.
 558 | 
 559 | The key to improving the performance of a very complicated system is to
 560 | analyze it well enough to find the _ bottlenecks_, or places where most of the
 561 | resources are consumed. There is not much sense in optimizing a function that
 562 | accounts for only 1% of the computation time. As a rule of thumb you should
 563 | think carefully before doing anything unless you think it is going to make the
 564 | system or a significant part of it at least twice as fast. There is usually a
 565 | way to do this. Consider the test and quality assurance effort that your
 566 | change will require. Each change brings a test burden with it, so it is much
 567 | better to have a few big changes.
 568 | 
 569 | After you've made a two-fold improvement in something, you need to at least
 570 | rethink and perhaps reanalyze to discover the next-most-expensive bottleneck
 571 | in the system, and attack that to get another two-fold improvement.
 572 | 
 573 | Often, the bottlenecks in performance will be an example of counting cows by
 574 | counting legs and dividing by four, instead of counting heads. For example,
 575 | I've made errors such as failing to provide a relational database system with
 576 | a proper index on a column I look up a lot, which probably made it at least 20
 577 | times slower. Other examples include doing unnecessary I/O in inner loops,
 578 | leaving in debugging statements that are no longer needed, unnecessary memory
 579 | allocation, and, in particular, inexpert use of libraries and other subsystems
 580 | that are often poorly documented with respect to performance. This kind of
 581 | improvement is sometimes called _ low-hanging fruit_, meaning that it can be
 582 | easily picked to provide some benefit.
 583 | 
 584 | What do you do when you start to run out of low-hanging fruit? Well, you can
 585 | reach higher, or chop the tree down. You can continue making small
 586 | improvements or you can seriously redesign a system or a subsystem. (This is a
 587 | great opportunity to use your skills as a good programmer, not only in the new
 588 | design but also in convincing your boss that this is a good idea.) However,
 589 | before you argue for the redesign of a subsystem, you should ask yourself
 590 | whether or not your proposal will make it five to ten time better.
 591 | 
 592 | ### How to Optimize Loops
 593 | 
 594 | Sometimes you'll encounter loops, or recursive functions, that take a long
 595 | time to execute and are bottlenecks in your product. Before you try to make
 596 | the loop a little faster, but spend a few minutes considering if there is a
 597 | way to remove it entirely. Would a different algorithm do? Could you compute
 598 | that while computing something else? If you can't find away around it, then
 599 | you can optimize the loop. This is simple; move stuff out. In the end, this
 600 | will require not only ingenuity but also an understanding of the expense of
 601 | each kind of statement and expression. Here are some suggestions:
 602 | 
 603 |   * Remove floating point operations. 
 604 | 
 605 |   * Don't allocate new memory blocks unnecessarily. 
 606 | 
 607 |   * Fold constants together. 
 608 | 
 609 |   * Move I/O into a buffer. 
 610 | 
 611 |   * Try not to divide. 
 612 | 
 613 |   * Try not to do expensive typecasts. 
 614 | 
 615 |   * Move a pointer rather than recomputing indices. 
 616 | 
 617 | The cost of each of these operations depends on your specific system. On some
 618 | systems compilers and hardware do these things for you. Clear, efficient code
 619 | is better than code that requires an understanding of a particular platform.
 620 | 
 621 | ### How to Deal with I/O Expense
 622 | 
 623 | For a lot of problems, processors are fast compared to the cost of
 624 | communicating with a hardware device. This cost is usually abbreviated I/O,
 625 | and can include network cost, disk I/O, database queries, file I/O, and other
 626 | use of some hardware not very close to the processor. Therefore building a
 627 | fast system is often more a question of improving I/O than improving the code
 628 | in some tight loop, or even improving an algorithm.
 629 | 
 630 | There are two very fundamental techniques to improving I/O: caching and
 631 | representation. Caching is avoiding I/O (generally avoiding the reading of
 632 | some abstract value) by storing a copy of that value locally so no I/O is
 633 | performed to get the value. The first key to caching is to make it crystal
 634 | clear which data is the _ master_ and which are _ copies_. There is only one
 635 | master---period. Caching brings with it the danger that the copy is sometimes
 636 | can't reflect changes to the master instantaneously.
 637 | 
 638 | Representation is the approach of making I/O cheaper by representing data more
 639 | efficiently. This is often in tension with other demands, like human
 640 | readability and portability.
 641 | 
 642 | Representations can often be improved by a factor of two or three from their
 643 | first implementation. Techniques for doing this include using a binary
 644 | representation instead of one that is human readable, transmitting a
 645 | dictionary of symbols along with the data so that long symbols don't have to
 646 | be encoded, and, at the extreme, things like Huffman encoding.
 647 | 
 648 | A third technique that is sometimes possible is to improve the locality of
 649 | reference by pushing the computation closer to the data. For instance, if you
 650 | are reading some data from a database and computing something simple from it,
 651 | such as a summation, try to get the database server to do it for you. This is
 652 | highly dependent on the kind of system you're working with, but you should
 653 | explore it.
 654 | 
 655 | ### How to Manage Memory
 656 | 
 657 | Memory is a precious resource that you can't afford to run out of. You can
 658 | ignore it for a while but eventually you will have to decide how to manage
 659 | memory.
 660 | 
 661 | Space that needs to persist beyond the scope of a single subroutine is often
 662 | called _ heap allocated_. A chunk of memory is useless, hence _ garbage_, when
 663 | nothing refers to it. Depending on the system you use, you may have to
 664 | explicitly deallocate memory yourself when it is about to become garbage. More
 665 | often you may be able to use a system that provides a _ garbage collector_. A
 666 | garbage collector notices garbage and frees its space without any action
 667 | required by the programmer. Garbage collection is wonderful: it lessens errors
 668 | and increases code brevity and concision cheaply. Use it when you can.
 669 | 
 670 | But even with garbage collection, you can fill up all memory with garbage. A
 671 | classic mistake is to use a hash table as a cache and forget to remove the
 672 | references in the hash table. Since the reference remains, the referent is
 673 | noncollectable but useless. This is called a _ memory leak_. You should look
 674 | for and fix memory leaks early. If you have long running systems memory may
 675 | never be exhausted in testing but will be exhausted by the user.
 676 | 
 677 | The creation of new objects is moderately expensive on any system. Memory
 678 | allocated directly in the local variables of a subroutine, however, is usually
 679 | cheap because the policy for freeing it can be very simple. You should avoid
 680 | unnecessary object creation.
 681 | 
 682 | An important case occurs when you can define an upper bound on the number of
 683 | objects you will need at one time. If these objects all take up the same
 684 | amount of memory, you may be able to allocate a single block of memory, or a
 685 | buffer, to hold them all. The objects you need can be allocated and released
 686 | inside this buffer in a set rotation pattern, so it is sometimes called a ring
 687 | buffer. This is usually faster than heap allocation.
 688 | 
 689 | Sometimes you have to explicitly free allocated space so it can be reallocated
 690 | rather than rely on garbage collection. Then you must apply careful
 691 | intelligence to each chunk of allocated memory and design a way for it to be
 692 | deallocated at the appropriate time. The method may differ for each kind of
 693 | object you create. You must make sure that every execution of a memory
 694 | allocating operation is matched by a memory deallocating operation eventually.
 695 | This is so difficult that programmers often simply implement a rudimentary
 696 | form or garbage collection, such as reference counting, to do this for them.
 697 | 
 698 | ### How to Deal with Intermittent Bugs
 699 | 
 700 | The intermittent bug is a cousin of the 50-foot-invisible-scorpion-from-outer-
 701 | space kind of bug. This nightmare occurs so rarely that it is hard to observe,
 702 | yet often enough that it can't be ignored. You can't debug because you can't
 703 | find it.
 704 | 
 705 | Although after 8 hours you will start to doubt it, the intermittent bug has to
 706 | obey the same laws of logic everything else does. What makes it hard is that
 707 | it occurs only under unknown conditions. Try to record the circumstances under
 708 | which the bug does occur, so that you can guess at what the variability really
 709 | is. The condition may be related to data values, such as 'This only happens
 710 | when we enter _ Wyoming_ as a value.' If that is not the source of
 711 | variability, the next suspect should be improperly synchronized concurrency.
 712 | 
 713 | Try, try, try to reproduce the bug in a controlled way. If you can't reproduce
 714 | it, set a trap for it by building a logging system, a special one if you have
 715 | to, that can log what you guess you need when it really does occur. Resign
 716 | yourself to that if the bug only occurs in production and not at your whim,
 717 | this is may be a long process. The hints that you get from the log may not
 718 | provide the solution but may give you enough information to improve the
 719 | logging. The improved logging system may take a long time to be put into
 720 | production. Then, you have to wait for the bug to reoccur to get more
 721 | information. This cycle can go on for some time.
 722 | 
 723 | The stupidest intermittent bug I ever created was in a multi-threaded
 724 | implementation of a functional programming language for a class project. I had
 725 | very carefully insured correct concurrent evaluation of the functional
 726 | program, good utilization of all the CPUs available (eight, in this case). I
 727 | simply forgot to synchronize the garbage collector. The system could run a
 728 | long time, often finishing whatever task I began, before anything noticeable
 729 | went wrong. I'm ashamed to admit I had begun to question the hardware before
 730 | my mistake dawned on me.
 731 | 
 732 | At work we recently had an intermittent bug that took us several weeks to
 733 | find. We have multi-threaded application servers in Java™ behind Apache™ web
 734 | servers. To maintain fast page turns, we do all I/O in small set of four
 735 | separate threads that are different than the page-turning threads. Every once
 736 | in a while these would apparently get 'stuck' and cease doing anything useful,
 737 | so far as our logging allowed us to tell, for hours. Since we had four
 738 | threads, this was not in itself a giant problem---unless all four got stuck.
 739 | Then the queues emptied by these threads would quickly fill up all available
 740 | memory and crash our server. It took us about a week to figure this much out,
 741 | and we still didn't know what caused it, when it would happen, or even what
 742 | the threads where doing when they got 'stuck'.
 743 | 
 744 | This illustrates some risk associated with third-party software. We were using
 745 | a licensed piece of code that removed HTML tags from text. Due to its place of
 746 | origin we affectionately referred to this as 'the French stripper.' Although
 747 | we had the source code (thank goodness!) we had not studied it carefully until
 748 | by turning up the logging on our servers we finally realized that the email
 749 | threads were getting stuck in the French stripper.
 750 | 
 751 | The stripper performed well except on some long and unusual kinds of texts. On
 752 | these texts, the code was quadratic or worse. This means that the processing
 753 | time was proportional to the square of the length of the text. Had these texts
 754 | occurred commonly, we would have found the bug right away. If they had never
 755 | occurred at all, we would never have had a problem. As it happens, it took us
 756 | weeks to finally understand and resolve the problem.
 757 | 
 758 | ### How to Learn Design Skills
 759 | 
 760 | To learn how to design software, study the action of a mentor by being
 761 | physically present when they are designing. Then study well-written pieces of
 762 | software. After that, you can read some books on the latest design techniques.
 763 | 
 764 | Then you must do it yourself. Start with a small project. When you are finally
 765 | done, consider how the design failed or succeeded and how you diverged from
 766 | your original conception. They move on to larger projects, hopefully in
 767 | conjunction with other people. Design is a matter of judgment that takes years
 768 | to acquire. A smart programmer can learn the basics adequately in two months
 769 | and can improve from there.
 770 | 
 771 | It is natural and helpful to develop your own style, but remember that design
 772 | is an art, not a science. People who write books on the subject have a vested
 773 | interest in making it seem scientific. Don't become dogmatic about particular
 774 | design styles.
 775 | 
 776 | ### How to Conduct Experiments
 777 | 
 778 | The late, great Edsger Dijkstra has eloquently explained that Computer Science
 779 | is not an experimental science[ExpCS] and doesn't depend on electronic
 780 | computers. As he puts it referring to the 1960s[Knife],
 781 | 
 782 | > ...the harm was done: the topic became known as "computer science"---which,
 783 | actually, is like referring to surgery as "knife science" --- and it was
 784 | firmly implanted in people's minds that computing science is about machines
 785 | and their peripheral equipment.
 786 | 
 787 | Programming ought not to be an experimental science, but most working
 788 | programmers do not have the luxury of engaging in what Dijkstra means by
 789 | computing science. We must work in the realm of experimentation, just as some,
 790 | but not all, physicists do. If thirty years from now programming can be
 791 | performed without experimentation, it will be a great accomplishment of
 792 | Computer Science.
 793 | 
 794 | The kinds of experiments you will have to perform include:
 795 | 
 796 |   * Testing systems with small examples to verify that they conform to the documentation or to understand their response when there is no documentation, 
 797 | 
 798 |   * Testing small code changes to see if they actually fix a bug, 
 799 | 
 800 |   * Measuring the performance of a system under two different conditions due to imperfect knowledge of there performance characteristics, 
 801 | 
 802 |   * Checking the integrity of data, and 
 803 | 
 804 |   * Collecting statistics that may hint at the solution to difficult or hard-to-repeat bugs. 
 805 | 
 806 | I don't think in this essay I can explain the design of experiments; you will
 807 | have to study and practice. However, I can offer two bits of advice.
 808 | 
 809 | First, try to be very clear about your hypothesis, or the assertion that you
 810 | are trying to test. It also helps to write the hypothesis down, especially if
 811 | you find yourself confused or are working with others.
 812 | 
 813 | You will often find yourself having to design a series of experiments, each of
 814 | which is based on the knowledge gained from the last experiment. Therefore,
 815 | you should design your experiments to provide the most information possible.
 816 | Unfortunately, this is in tension with keeping each experiment simple---you
 817 | will have to develop this judgment through experience.
 818 | 
 819 | ## Team Skills
 820 | 
 821 | ### Why Estimation is Important
 822 | 
 823 | To get a working software system in active use as quickly as possible requires
 824 | not only planning the development, but also planning the documentation,
 825 | deployment, marketing. In a commercial project it also requires sales and
 826 | finance. Without predictability of the development time, it is impossible to
 827 | plan these effectively.
 828 | 
 829 | Good estimation provides predictability. Managers love it, as well they
 830 | should. The fact that it is impossible, both theoretically and practically, to
 831 | predict accurately how long it will take to develop software is often lost on
 832 | managers. We are asked to do this impossible thing all the time, and we must
 833 | face up to it honestly. However, it would be dishonest not to admit the
 834 | impossibility of this task, and when necessary, explain it. There is a lot of
 835 | room for miscommunication about estimates, as people have a startling tendency
 836 | to think wishfully that the sentence:
 837 | 
 838 | > I estimate that, if I really understand the problem, it is about 50% likely
 839 | that we will be done in five weeks (if no one bothers us during that time).
 840 | 
 841 | really means:
 842 | 
 843 | > I promise to have it all done five weeks from now.
 844 | 
 845 | This common interpretation problem requires that you explicitly discuss what
 846 | the estimate means with your boss or customer as if they were a simpleton.
 847 | Restate your assumptions, no matter how obvious they seem to you.
 848 | 
 849 | ### How to Estimate Programming Time
 850 | 
 851 | Estimation takes practice. It also takes labor. It takes so much labor it may
 852 | be a good idea to estimate the time it will take to make the estimate,
 853 | especially if you are asked to estimate something big.
 854 | 
 855 | When asked to provide an estimate of something big, the most honest thing to
 856 | do is to stall. Most engineers are enthusiastic and eager to please, and
 857 | stalling certainly will displease the stalled. But an on-the-spot estimate
 858 | probably won't be accurate and honest.
 859 | 
 860 | While stalling, it may be possible to consider doing or prototyping the task.
 861 | If political pressure permits, this is the most accurate way of producing the
 862 | estimate, and it makes real progress.
 863 | 
 864 | When not possible to take the time for some investigation, you should first
 865 | establish the meaning of the estimate very clearly. Restate that meaning as
 866 | the first and last part of your written estimate. Prepare a written estimate
 867 | by deconstructing the task into progressively smaller subtasks until each
 868 | small task is no more than a day; ideally at most in length. The most
 869 | important thing is not to leave anything out. For instance, documentation,
 870 | testing, time for planning, time for communicating with other groups, and
 871 | vacation time are all very important. If you spend part of each day dealing
 872 | with knuckleheads, put a line item for that in the estimate. This gives your
 873 | boss visibility into what is using up your time at a minimum, and might get
 874 | you more time.
 875 | 
 876 | I know good engineers who pad estimates implicitly, but I recommend that you
 877 | do not. One of the results of padding is trust in you may be depleted. For
 878 | instance, an engineer might estimate three days for a task that she truly
 879 | thinks will take one day. The engineer may plan to spend two days documenting
 880 | it, or two days working on some other useful project. But it will be
 881 | detectable that the task was done in only one day (if it turns out that way),
 882 | and the appearance of slacking or overestimating is born. It's far better to
 883 | give proper visibility into what you are actually doing. If documentation
 884 | takes twice as long as coding and the estimate says so, tremendous advantage
 885 | is gained by making this visible to the manager.
 886 | 
 887 | Pad explicitly instead. If a task will probably take one day---but might take
 888 | ten days if your approach doesn't work---note this somehow in the estimate if
 889 | you can; if not, at least do an average weighted by your estimates of the
 890 | probabilities. Any risk factor that you can identify and assign an estimate to
 891 | should go into the schedule. One person is unlikely to be sick in any given
 892 | week. But a large project with many engineers will have some sick time;
 893 | likewise vacation time. And what is the probability of a mandatory company-
 894 | wide training seminar? If it can be estimated, stick it in. There are of
 895 | course, unknown unknowns, or _ unk-unks_. Unk-unks by definition cannot be
 896 | estimated individually. You can try to create a global line item for all unk-
 897 | unks, or handle them in some other way that you communicate to your boss. You
 898 | cannot, however, let your boss forget that they exist, and it is devilishly
 899 | easy for an estimate to become a schedule without the unk-unks considered.
 900 | 
 901 | In a team environment, you should try to have the people who will do the work
 902 | do the estimate, and you should try to have team-wide consensus on estimates.
 903 | People vary widely in skill, experience, preparedness, and confidence.
 904 | Calamity strikes when a strong programmer estimates for herself and then weak
 905 | programmers are held to this estimate. The act of having the whole team agree
 906 | on a line-by-line basis to the estimate clarifies the team understanding, as
 907 | well as allowing the opportunity for tactical reassignment of resources (for
 908 | instance, shifting burden away from weaker team members to stronger).
 909 | 
 910 | If there are big risks that cannot be evaluated, it is your duty to state so
 911 | forcefully enough that your manager does not commit to them and then become
 912 | embarrassed when the risk occurs. Hopefully in such a case whatever is needed
 913 | will be done to decrease the risk.
 914 | 
 915 | If you can convince your company to use _ Extreme Programming_, you will only
 916 | have to estimate relatively small things, and this is both more fun and more
 917 | productive.
 918 | 
 919 | ### How to Find Out Information
 920 | 
 921 | The nature of what you need to know determines how you should find it.
 922 | 
 923 | If you need information _about concrete things_ that are objective and easy to
 924 | verify, for example the latest patch level of a software product, ask a large
 925 | number of people politely by searching the internet for it or by posting on a
 926 | discussion group. Don't search on the internet for anything that smacks of
 927 | either opinion or subjective interpretation: the ratio of drivel to truth is
 928 | too high.
 929 | 
 930 | If you need _general knowledge about something subjective_ the history of what
 931 | people have thought about it, go to the library (the physical building in
 932 | which books are stored). For example, to learn about math or mushrooms or
 933 | mysticism, go to the library.
 934 | 
 935 | If you need to know _how to do something that is not trivial_ get two or three
 936 | books on the subject and read them. You might learn how to do something
 937 | trivial, like install a software package, from the Internet. You can even
 938 | learn important things, like good programming technique, but you can easily
 939 | spend more time searching and sorting the results and attempting to divine the
 940 | authority of the results than it would take to read the pertinent part of a
 941 | solid book.
 942 | 
 943 | If you need _information that no one else could be expected to know_ for
 944 | example, 'does this software that is brand new work on gigantic data sets?',
 945 | you must still search the internet and the library. After those options are
 946 | completely exhausted, you may design an experiment to ascertain it.
 947 | 
 948 | If you want an opinion or a value judgment that takes into account some unique
 949 | circumstance, talk to an expert. For instance, if you want to know whether or
 950 | not it is a good idea to build a modern database management system in LISP,
 951 | you should talk to a LISP expert and a database expert.
 952 | 
 953 | If you want to know _how likely it is_ that a faster algorithm for a
 954 | particular application exists that has not yet been published, talk to someone
 955 | working in that field.
 956 | 
 957 | If you want to make a _personal decision that only you can make_ like whether
 958 | or not you should start a business, try putting into writing a list of
 959 | arguments for and against the idea. If that fails, consider divination.
 960 | Suppose you have studied the idea from all angles, have done all your
 961 | homework, and worked out all the consequences and pros and cons in your mind,
 962 | and yet still remain indecisive. You now must follow your heart and tell your
 963 | brain to shut up. The multitude of available divination techniques are very
 964 | useful for determining your own semi-conscious desires, as they each present a
 965 | complete ambiguous and random pattern that your own subconscious will assign
 966 | meaning to.
 967 | 
 968 | ### How to Utilize People as Information Sources
 969 | 
 970 | Respect every person's time and balance it against your own. Asking someone a
 971 | question accomplishes far more than just receiving the answer. The person
 972 | learns about you, both by enjoying your presence and hearing the particular
 973 | question. You learn about the person in the same way, and you may learn the
 974 | answer you seek. This is usually far more important than your question.
 975 | 
 976 | However, the value of this diminishes the more you do it. You are, after all,
 977 | using the most precious commodity a person has: their time. The benefits of
 978 | communication must be weighed against the costs. Furthermore, the particular
 979 | costs and benefits derived differ from person to person. I strongly believe
 980 | that an executive of 100 people should spend five minutes a month talking to
 981 | each person in her organization, which would be about 5% of their time. But
 982 | ten minutes might be too much, and five minutes is too much if they have one
 983 | thousand employees. The amount of time you spend talking to each person in
 984 | your organization depends on their role (more than their position). You should
 985 | talk to your boss more than your boss's boss, but you should talk to your
 986 | boss's boss a little. It may be uncomfortable, but I believe you have a duty
 987 | to talk a little bit to all your superiors, each month, no matter what.
 988 | 
 989 | The basic rule is that everyone benefits from talking to you a little bit, and
 990 | the more they talk to you, the less benefit they derive. It is your job to
 991 | provide them this benefit, and to get the benefit of communicating with them,
 992 | keeping the benefit in balance with the time spent.
 993 | 
 994 | It is important to respect your own time. If talking to someone, even if it
 995 | will cost them time, will save you a great deal of time, then you should do it
 996 | unless you think their time is more valuable than yours, to the tribe, by that
 997 | factor.
 998 | 
 999 | A strange example of this is the summer intern. A summer intern in a highly
1000 | technical position can't be expected to accomplish too much; they can be
1001 | expected to pester the hell out of everybody there. So why is this tolerated?
1002 | Because the pestered are receiving something important from the intern. They
1003 | get a chance to showoff a little. They get a chance to hear some new ideas,
1004 | maybe; they get a chance to see things from a different perspective. They may
1005 | also be trying to recruit the intern, but even if this is not the case there
1006 | is much to gain.
1007 | 
1008 | You should ask people for a little bit of their wisdom and judgment whenever
1009 | you honestly believe they have something to say. This flatters them and you
1010 | will learn something and teach them something. A good programmer does not
1011 | often need the advice of a Vice President of Sales, but if you ever do, you be
1012 | sure to ask for it. I once asked to listen in on a few sales calls to better
1013 | understand the job of our sales staff. This took no more than 30 minutes but I
1014 | think that small effort made an impression on the sales force.
1015 | 
1016 | ### How to Document Wisely
1017 | 
1018 | Life is too short to write crap nobody will read; if you write crap, nobody
1019 | will read it. Therefore a little good documentation is best. Managers often
1020 | don't understand this, because even bad documentation gives them a false sense
1021 | of security that they are not dependent on their programmers. If someone
1022 | absolutely insists that you write truly useless documentation, say ``yes'' and
1023 | quietly begin looking for a better job.
1024 | 
1025 | There's nothing quite as effective as putting an accurate estimate of the
1026 | amount of time it will take to produce good documentation into an estimate to
1027 | slacken the demand for documentation. The truth is cold and hard:
1028 | documentation, like testing, can take many times longer than developing code.
1029 | 
1030 | Writing good documentation is, first of all, good writing. I suggest you find
1031 | books on writing, study them, and practice. But even if you are a lousy writer
1032 | or have poor command of the language in which you must document, the Golden
1033 | Rule is all you really need: ``Do unto others as you would have them do unto
1034 | you.'' Take time to really think about who will be reading your documentation,
1035 | what they need to get out of it, and how you can teach that to them. If you do
1036 | that, you will be an above average documentation writer, and a good
1037 | programmer.
1038 | 
1039 | When it comes to actually documenting code itself, as opposed to producing
1040 | documents that can actually be read by non-programmers, the best programmers
1041 | I've ever known hold a universal sentiment: write self-explanatory code and
1042 | only document code in the places that you cannot make it clear by writing the
1043 | code itself. There are two good reasons for this. First, anyone who needs to
1044 | see code-level documentation will in most cases be able to and prefer to read
1045 | the code anyway. Admittedly, this seems easier to the experienced programmer
1046 | than to the beginner. More importantly however, is that the code and the
1047 | documentation cannot be inconsistent if there is no documentation. The source
1048 | code can at worst be wrong and confusing. The documentation, if not written
1049 | perfectly, can lie, and that is a thousand times worse.
1050 | 
1051 | This does not make it easier on the responsible programmer. How does one write
1052 | self-explanatory code? What does that even mean? It means:
1053 | 
1054 |   * Writing code knowing that someone will have to read it; 
1055 | 
1056 |   * Applying the golden rule; 
1057 | 
1058 |   * Choosing a solution that is straightforward, even if you could get by with another solution faster; 
1059 | 
1060 |   * Sacrificing small optimizations that obfuscate the code; 
1061 | 
1062 |   * Thinking about the reader and spending some of your precious time to make it easier on her; and 
1063 | 
1064 |   * Not ever using a function name like ``foo'',``bar'', or ``doIt''! 
1065 | 
1066 | ### How to Work with Poor Code
1067 | 
1068 | It is very common to have to work with poor quality code that someone else has
1069 | written. Don't think too poorly of them, however, until you have walked in
1070 | their shoes. They may have been asked very consciously to get something done
1071 | quickly to meet schedule pressure. Regardless, in order to work with unclear
1072 | code you must understand it. To understand it takes learning time, and that
1073 | time will have to come out of some schedule, somewhere, and you must insist on
1074 | it. To understand it, you will have to read the source code. You will probably
1075 | have to experiment with it.
1076 | 
1077 | This is a good time to document, even if it is only for yourself, because the
1078 | act of trying to document the code will force you to consider angles you might
1079 | not have considered, and the resulting document may be useful. While you're
1080 | doing this, consider what it would take to rewrite some or all of the code.
1081 | Would it actually save time to rewrite some of it? Could you trust it better
1082 | if you rewrote it? Be careful of arrogance here. If you rewrite it, it will be
1083 | easier for you to deal with, but will it really be easier for the next person
1084 | who has to read it? If you rewrite it, what will the test burden be? Will the
1085 | need to re-test it outweigh any benefits that might be gained?
1086 | 
1087 | In any estimate that you make for work against code you didn't write, the
1088 | quality of that code should affect your perception of the risk of problems and
1089 | unk-unks.
1090 | 
1091 | It is important to remember that abstraction and encapsulation, two of a
1092 | programmer's best tools, are particularly applicable to lousy code. You may
1093 | not be able to redesign a large block of code, but if you can add a certain
1094 | amount of abstraction to it you can obtain some of the benefits of a good
1095 | design without reworking the whole mess. In particular, you can try to wall
1096 | off the parts that are particularly bad so that they may be redesigned
1097 | independently.
1098 | 
1099 | ### How to Use Source Code Control
1100 | 
1101 | Source code control systems let you manage projects effectively. They're very
1102 | useful for one person and essential for a group. They track all changes in
1103 | different versions so that no code is ever lost and meaning can be assigned to
1104 | changes. One can create throw-away and debugging code with confidence with a
1105 | source code control system, since the code you modify is kept carefully
1106 | separate from committed, official code that will be shared with the team or
1107 | released.
1108 | 
1109 | I was late to appreciate the benefits of source code control systems but now I
1110 | wouldn't live without one even on a one-person project. Generally they are
1111 | necessary when you have team working on the same code base. However, they have
1112 | another great advantage: they encourage thinking about the code as a growing,
1113 | organic system. Since each change is marked as a new revision with a new name
1114 | or number, one begins to think of the software as a visibly progressive series
1115 | of improvements. I think this is especially useful for beginners.
1116 | 
1117 | A good technique for using a source code control system is to stay within a
1118 | few days of being up-to-date at all time. Code that can't be finished in a few
1119 | days is checked in, but in a way that it is inactive and will not be called,
1120 | and therefore not create any problems for anybody else. Committing a mistake
1121 | that slows down your teammates is a serious error; it is often taboo.
1122 | 
1123 | ### How to Unit Test
1124 | 
1125 | Unit testing, the testing of an individual piece of coded functionality by the
1126 | team that wrote it, is a part of coding, not something different from it. Part
1127 | of designing the code is designing how it will be tested. You should write
1128 | down a test plan, even if it is only one sentence. Sometimes the test will be
1129 | simple: ``Does the button look good?'' Sometimes it will be complex: ``Did
1130 | this matching algorithm return precisely the correct matches?''
1131 | 
1132 | Use assertion checking and test drivers whenever possible. This not only
1133 | catches bugs early, but is very useful later on and lets you eliminate
1134 | mysteries that you would otherwise have to worry about.
1135 | 
1136 | The Extreme Programming developers are writing extensively on unit testing
1137 | effectively; I can do no better than to recommend their writings.
1138 | 
1139 | ### Take Breaks when Stumped
1140 | 
1141 | When stumped, take a break. I sometimes meditate for 15 minutes when stumped
1142 | and the problem magically unravels when I come back to it. A night's sleep
1143 | sometimes does the same thing on a larger scale. It's possible that
1144 | temporarily switching to any other activity may work.
1145 | 
1146 | ### How to Recognize When to Go Home
1147 | 
1148 | Computer programming is an activity that is also a culture. The unfortunate
1149 | fact is that it is not a culture that values mental or physical health very
1150 | much. For both cultural/historical reasons (the need to work at night on
1151 | unloaded computers, for example) and because of overwhelming time-to-market
1152 | pressure and the scarcity of programmers, computer programmers are
1153 | traditionally overworked. I don't think you can trust all the stories you
1154 | hear, but I think 60 hours a week is common, and 50 is pretty much a minimum.
1155 | This means that often much more than that is required. This is serious problem
1156 | for a good programmer, who is responsible not only for themselves but their
1157 | teammates as well. You have to recognize when to go home, and sometimes when
1158 | to suggest that other people go home. There can't be any fixed rules for
1159 | solving this problem, anymore than there can be fixed rules for raising a
1160 | child, for the same reason---every human being is different.
1161 | 
1162 | Beyond 60 hours a week is an extraordinary effort for me, which I can apply
1163 | for short periods of time (about one week), and that is sometimes expected of
1164 | me. I don't know if it is fair to expect 60 hours of work from a person; I
1165 | don't even know if 40 is fair. I am sure, however, that it is stupid to work
1166 | so much that you are getting little out of that extra hour you work. For me
1167 | personally, that's any more than 60 hours a week. I personally think a
1168 | programmer should exercise noblesse oblige and shoulder a heavy burden.
1169 | However, it is not a programmer's duty to be a patsy. The sad fact is
1170 | programmers _are_ often asked to be patsies in order to put on a show for
1171 | somebody, for example a manager trying to impress an executive. Programmers
1172 | often succumb to this because they are eager to please and not very good at
1173 | saying no. There are four defenses against this:
1174 | 
1175 |   * Communicate as much as possible with everyone in the company so that no one can mislead the executives about what is going on, 
1176 | 
1177 |   * Learn to estimate and schedule defensively and explicitly and give everyone visibility into what the schedule is and where it stands, 
1178 | 
1179 |   * Learn to say no, and say no as a team when necessary, and 
1180 | 
1181 |   * Quit if you have to. 
1182 | 
1183 | Most programmers are good programmers, and good programmers want to get a lot
1184 | done. To do that, they have to manage their time effectively. There is a
1185 | certain amount of mental inertia associated with getting warmed-up to a
1186 | problem and deeply involved in it. Many programmers find they work best when
1187 | they have long, uninterrupted blocks of time in which to get warmed-up and
1188 | concentrate. However, people must sleep and perform other duties. Each person
1189 | needs to find a way to satisfy both their human rhythm and their work rhythm.
1190 | Each programmer needs to do whatever it takes to procure efficient work
1191 | periods, such as reserving certain days in which you will attend only the most
1192 | critical meetings.
1193 | 
1194 | Since I have children, I try to spend evenings with them sometimes. The rhythm
1195 | that works best for me is to work a very long day, sleep in the office or near
1196 | the office (I have a long commute from home to work) then go home early enough
1197 | the next day to spend time with my children before they go to bed. I am not
1198 | comfortable with this, but it is the best compromise I have been able to work
1199 | out. Go home if you have a contagious disease. You should go home if you are
1200 | thinking suicidal thoughts. You should take a break or go home if you think
1201 | homicidal thoughts for more than a few seconds. You should send someone home
1202 | if they show serious mental malfunctioning or signs of mental illness beyond
1203 | mild depression. If you are tempted to be dishonest or deceptive in a way that
1204 | you normally are not due to fatigue, you should take a break. Don't use
1205 | cocaine or amphetamines to combat fatigue. Don't abuse caffeine.
1206 | 
1207 | ### How to Deal with Difficult People
1208 | 
1209 | You will probably have to deal with difficult people. You may even be a
1210 | difficult person yourself. If you are the kind of person who has a lot of
1211 | conflicts with coworkers and authority figures, you should cherish the
1212 | independence this implies, but work on your interpersonal skills without
1213 | sacrificing your intelligence or principles.
1214 | 
1215 | This can be very disturbing to some programmers who have no experience in this
1216 | sort of thing and whose previous life experience has taught them patterns of
1217 | behavior that are not useful in the workplace. Difficult people are often
1218 | inured to disagreement and they are less affected by social pressure to
1219 | compromise than others. The key is to respect them appropriately, which is
1220 | more than you will want to but not as much as they might want.
1221 | 
1222 | Programmers have to work together as a team. When disagreement arises, it must
1223 | be resolved somehow, it cannot be ducked for long. Difficult people are often
1224 | extremely intelligent and have something very useful to say. It is critical
1225 | that you listen and understand the difficult person without prejudice caused
1226 | by the person. A failure to communicate is often the basis of disagreement but
1227 | it can sometimes be removed with great patience. Try to keep this
1228 | communication cool and cordial, and don't accept any baits for greater
1229 | conflict that may be offered. After a reasonable period of trying to
1230 | understand, make a decision.
1231 | 
1232 | Don't let a bully force you to do something you don't agree with. If you are
1233 | the leader, do what you think is best. Don't make a decision for any personal
1234 | reasons, and be prepared to explain the reasons for your decision. If you are
1235 | a teammate with a difficult person, don't let the leader's decision have any
1236 | personal impact. If it doesn't go your way, do it the other way whole-
1237 | heartedly.
1238 | 
1239 | Difficult people do change and improve. I've seen it with my own eyes, but it
1240 | is very rare. However, everyone has transitory ups and downs.
1241 | 
1242 | One of the challenges that every programmer but especially leaders face is
1243 | keeping the difficult person fully engaged. They are more prone to duck work
1244 | and resist passively than others.
1245 | 
1246 | ## Chapter 3. Intermediate
1247 | 
1248 | **Table of Contents**
1249 | 
1250 | Personal Skills
1251 | 
1252 |     
1253 | 
1254 | How to Stay Motivated
1255 | 
1256 | How to be Widely Trusted
1257 | 
1258 | How to Tradeoff Time vs. Space
1259 | 
1260 | How to Stress Test
1261 | 
1262 | How to Balance Brevity and Abstraction
1263 | 
1264 | How to Learn New Skills
1265 | 
1266 | Learn to Type
1267 | 
1268 | How to Do Integration Testing
1269 | 
1270 | Communication Languages
1271 | 
1272 | Heavy Tools
1273 | 
1274 | How to analyze data
1275 | 
1276 | Team Skills
1277 | 
1278 |     
1279 | 
1280 | How to Manage Development Time
1281 | 
1282 | How to Manage Third-Party Software Risks
1283 | 
1284 | How to Manage Consultants
1285 | 
1286 | How to Communicate the Right Amount
1287 | 
1288 | How to Disagree Honestly and Get Away with It
1289 | 
1290 | Judgement
1291 | 
1292 |     
1293 | 
1294 | How to Tradeoff Quality Against Development Time
1295 | 
1296 | How to Manage Software System Dependence
1297 | 
1298 | How to Decide if Software is Too Immature
1299 | 
1300 | How to Make a Buy vs. Build Decision
1301 | 
1302 | How to Grow Professionally
1303 | 
1304 | How to Evaluate Interviewees
1305 | 
1306 | How to Know When to Apply Fancy Computer Science
1307 | 
1308 | How to Talk to Non-Engineers
1309 | 
1310 | ## Personal Skills
1311 | 
1312 | ### How to Stay Motivated
1313 | 
1314 | It is a wonderful and surprising fact that programmers are highly motivated by
1315 | the desire to create artifacts that are beautiful, useful, or nifty. This
1316 | desire is not unique to programmers nor universal but it is so strong and
1317 | common among programmers that it separates them from others in other roles.
1318 | 
1319 | This has practical and important consequences. If programmers are asked to do
1320 | something that is not beautiful, useful, or nifty, they will have low morale.
1321 | There's a lot of money to be made doing ugly, stupid, and boring stuff; but in
1322 | the end, fun will make the most money for the company.
1323 | 
1324 | Obviously, there are entire industries organized around motivational
1325 | techniques some of which apply here. The things that are specific to
1326 | programming that I can identify are:
1327 | 
1328 |   * Use the best language for the job. 
1329 | 
1330 |   * Look for opportunities to apply new techniques, languages, and technologies. 
1331 | 
1332 |   * Try to either learn or teach something, however small, in each project. 
1333 | 
1334 | Finally, if possible, measure the impact of your work in terms of something
1335 | that will be personally motivating. For example, when fixing bugs, counting
1336 | the number of bugs that I have fixed is not at all motivational to me, because
1337 | it is independent of the number that may still exist, and is also affects the
1338 | total value I'm adding to my company's customers in only the smallest possible
1339 | way. Relating each bug to a happy customer, however, _is_ personally
1340 | motivating to me.
1341 | 
1342 | ### How to be Widely Trusted
1343 | 
1344 | To be trusted you must be trustworthy. You must also be visible. If know one
1345 | knows about you, no trust will be invested in you. With those close to you,
1346 | such as your teammates, this should not be an issue. You establish trust by
1347 | being responsive and informative to those outside your department or team.
1348 | Occasionally someone will abuse this trust, and ask for unreasonable favors.
1349 | Don't be afraid of this, just explain what you would have to give up doing to
1350 | perform the favor.
1351 | 
1352 | Don't pretend to know something that you don't. With people that are not
1353 | teammates, you may have to make a clear distinction between ``not knowing
1354 | right off the top of my head'' and ``not being able to figure it out, ever.''
1355 | 
1356 | ### How to Tradeoff Time vs. Space
1357 | 
1358 | You can be a good programmer without going to college, but you can't be a good
1359 | intermediate programmer without knowing basic computational complexity theory.
1360 | You don't need to know ``big O'' notation, but I personally think you should
1361 | be able to understand the difference between ``constant-time'',``n log n'' and
1362 | ``n squared''. You might be able to intuit how to tradeoff time against space
1363 | without this knowledge, but in its absence you will not have a firm basis for
1364 | communicating with your colleagues.
1365 | 
1366 | In designing or understanding an algorithm, the amount of time it takes to run
1367 | is sometimes a function of the size of the input. When that is true, we can
1368 | say an algorithm's worst/expected/best-case running time is ``n log n'' if it
1369 | is proportional to the size ($n$) times the logarithm of the size. The
1370 | notation and way of speaking can be also be applied to the space taken up by a
1371 | data structure.
1372 | 
1373 | To me, computational complexity theory is beautiful and as profound as physics
1374 | ---and a little bit goes a long way!
1375 | 
1376 | Time (processor cycles) and space (memory) can be traded off against each
1377 | other. Engineering is about compromise, and this is a fine example. It is not
1378 | always systematic. In general, however, one can save space by encoding things
1379 | more tightly, at the expense of more computation time when you have to decode
1380 | them. You can save time by caching, that is, spending space to store a local
1381 | copy of something, at the expense of having to maintain the consistency of the
1382 | cache. You can sometimes save time by maintaining more information in a data
1383 | structure. This usually cost a small amount of space but may complicate the
1384 | algorithm.
1385 | 
1386 | Improving the space/time tradeoff can often change one or the other
1387 | dramatically. However, before you work on this you should ask yourself if what
1388 | you are improving is really the thing that needs the most improvement. It's
1389 | fun to work on an algorithm, but you can't let that blind you to the cold hard
1390 | fact that improving something that is not a problem will not make any
1391 | noticeable difference and will create a test burden.
1392 | 
1393 | Memory on modern computers appears cheap, because unlike processor time, you
1394 | can't see it being used until you hit the wall; but then failure is
1395 | catastrophic. There are also other hidden costs to using memory, such as your
1396 | effect on other programs that must be resident, and the time to allocate and
1397 | deallocate it. Consider this carefully before you trade away space to gain
1398 | speed.
1399 | 
1400 | ### How to Stress Test
1401 | 
1402 | Stress testing is fun. At first it appears that the purpose of stress testing
1403 | is to find out if the system works under a load. In reality, it is common that
1404 | the system does work under a load but fails to work in some way when the load
1405 | is heavy enough. I call this _ hitting the wall_ or _ bonking_[1]. There may
1406 | be some exceptions, but there is almost always a 'wall'. The purpose of stress
1407 | testing is to figure out where the wall is, and then figure out how to move
1408 | the wall further out.
1409 | 
1410 | A plan for stress testing should be developed early in the project, because it
1411 | often helps to clarify exactly what is expected. Is two seconds for a web page
1412 | request a miserable failure or a smashing success? Is 500 concurrent users
1413 | enough? That, of course, depends, but one must know the answer when designing
1414 | the system that answers the request. The stress test needs to model reality
1415 | well enough to be useful. It isn't really possible to simulate 500 erratic and
1416 | unpredictable humans using a system concurrently very easily, but one can at
1417 | least create 500 simulations and try to model some part of what they might do.
1418 | 
1419 | In stress testing, start out with a light load and load the system along some
1420 | dimension---such as input rate or input size---until you hit the wall. If the
1421 | wall is too close to satisfy your needs, figure out which resource is the
1422 | bottleneck (there is usually a dominant one.) Is it memory, processor, I/O,
1423 | network bandwidth, or data contention? Then figure out how you can move the
1424 | wall. Note that moving the wall, that is, increasing the maximum load the
1425 | system can handle, might not help or might actually hurt the performance of a
1426 | lightly loaded system. Usually performance under heavy load is more important
1427 | than performance under a light load.
1428 | 
1429 | You may have to get visibility into several different dimensions to build up a
1430 | mental model of it; no single technique is sufficient. For instance, logging
1431 | often gives a good idea of the wall-clock time between two events in the
1432 | system, but unless carefully constructed, doesn't give visibility into memory
1433 | utilization or even data structure size. Similarly, in a modern system, a
1434 | number of computers and many software systems may be cooperating. Particularly
1435 | when you are hitting the wall (that is, the performance is non-linear in the
1436 | size of the input) these other software systems may be a bottleneck.
1437 | Visibility into these systems, even if only measuring the processor load on
1438 | all participating machines, can be very helpful.
1439 | 
1440 | Knowing where the wall is is essential not only to moving the wall, but also
1441 | to providing predictability so that the business can be managed effectively.
1442 | 
1443 | ### How to Balance Brevity and Abstraction
1444 | 
1445 | Abstraction is key to programming. You should carefully choose how abstract
1446 | you need to be. Beginning programmers in their enthusiasm often create more
1447 | abstraction than is really useful. One sign of this is if you create classes
1448 | that don't really contain any code and don't really do anything except serve
1449 | to abstract something. The attraction of this is understandable but the value
1450 | of code brevity must be measured against the value of abstraction.
1451 | Occasionally, one sees a mistake made by enthusiastic idealists: at the start
1452 | of the project a lot of classes are defined that seem wonderfully abstract and
1453 | one may speculate that they will handle every eventuality that may arise. As
1454 | the project progresses and fatigue sets in, the code itself becomes messy.
1455 | Function bodies become longer than they should be. The empty classes are a
1456 | burden to document that is ignored when under pressure. The final result would
1457 | have been better if the energy spent on abstraction had been spent on keeping
1458 | things short and simple. This is a form of _ speculative programming_. I
1459 | strongly recommend the article ``Succinctness is Power'' by Paul
1460 | Graham[PGSite].
1461 | 
1462 | There is a certain dogma associated with useful techniques such as _
1463 | information hiding_ and _ object oriented programming_ that are sometimes
1464 | taken too far. These techniques let one code abstractly and anticipate change.
1465 | I personally think, however, that you should not produce much speculative
1466 | code. For example, it is an accepted style to hide an integer variable on an
1467 | object behind mutators and accessors, so that the variable itself is not
1468 | exposed, only the little interface to it. This does allow the implementation
1469 | of that variable to be changed without affecting the calling code, and is
1470 | perhaps appropriate to a library writer who must publish a very stable API.
1471 | But I don't think the benefit of this outweighs the cost of the wordiness of
1472 | it when my team owns the calling code and hence can recode the caller as
1473 | easily as the called. Four or five extra lines of code is a heavy price to pay
1474 | for this speculative benefit.
1475 | 
1476 | Portability poses a similar problem. Should code be portable to a different
1477 | computer, compiler, software system or platform, or simply easily ported? I
1478 | think a non-portable, short-and-easily-ported piece of code is better than a
1479 | long portable one. It is relatively easy and certainly a good idea to confine
1480 | non-portable code to designated areas, such as a class that makes database
1481 | queries that are specific to a given DBMS.
1482 | 
1483 | ### How to Learn New Skills
1484 | 
1485 | Learning new skills, especially non-technical ones, is the greatest fun of
1486 | all. Most companies would have better morale if they understood how much this
1487 | motivates programmers.
1488 | 
1489 | Humans learn by doing. Book-reading and class-taking are useful. But could you
1490 | have any respect for a programmer who had never written a program? To learn
1491 | any skill, you have to put yourself in a forgiving position where you can
1492 | exercise that skill. When learning a new programming language, try to do a
1493 | small project it in before you have to do a large project. When learning to
1494 | manage a software project, try to manage a small one first.
1495 | 
1496 | A good mentor is no replacement for doing things yourself, but is a lot better
1497 | than a book. What can you offer a potential mentor in exchange for their
1498 | knowledge? At a minimum, you should offer to study hard so their time won't be
1499 | wasted.
1500 | 
1501 | Try to get your boss to let you have formal training, but understand that it
1502 | often not much better than the same amount of time spent simply playing with
1503 | the new skill you want to learn. It is, however, easier to ask for training
1504 | than playtime in our imperfect world, even though a lot of formal training is
1505 | just sleeping through lectures waiting for the dinner party.
1506 | 
1507 | If you lead people, understand how they learn and assist them by assigning
1508 | them projects that are the right size and that exercise skills they are
1509 | interested in. Don't forget that the most important skills for a programmer
1510 | are not the technical ones. Give your people a chance to play and practice
1511 | courage, honesty, and communication.
1512 | 
1513 | ### Learn to Type
1514 | 
1515 | Learn to touch-type. This is an intermediate skill because writing code is so
1516 | hard that the speed at which you can type is irrelevant and can't put much of
1517 | a dent in the time it takes to write code, no matter how good you are.
1518 | However, by the time you are an intermediate programmer you will probably
1519 | spend a lot of time writing natural language to your colleagues and others.
1520 | This is a fun test of your commitment; it takes dedicated time that is not
1521 | much fun to learn something like that. Legend has it that when Michael
1522 | Tiemann[2] was at MCC people would stand outside his door to listen to the hum
1523 | generated by his keystrokes which were so rapid as to be indistinguishable.
1524 | 
1525 | ### How to Do Integration Testing
1526 | 
1527 | Integration testing is the testing of the integration of various components
1528 | that have been unit tested. Integration is expensive and it comes out in the
1529 | testing. You must include time for this in your estimates and your schedule.
1530 | 
1531 | Ideally you should organize a project so that there is not a phase at the end
1532 | where integration must explicitly take place. It is far better to gradually
1533 | integrate things as they are completed over the course of the project. If it
1534 | is unavoidable estimate it carefully.
1535 | 
1536 | ### Communication Languages
1537 | 
1538 | There are some languages, that is, formally defined syntactic systems, that
1539 | are not programming languages but _ communication languages_---they are
1540 | designed specifically to facillitate communication through standardization. In
1541 | 2003 the most important of these are UML, XML, and SQL. You should have some
1542 | familiarity with all of these so that you can communicate well and decide when
1543 | to use them.
1544 | 
1545 | UML is a rich formal system for making drawings that describe designs. It's
1546 | beauty lines in that is both visual and formal, capable of conveying a great
1547 | deal of information if both the author and the audience know UML. You need to
1548 | know about it because designs are sometimes communicated in it. There are very
1549 | helpful tools for making UML drawings that look very professional. In a lot of
1550 | cases UML is too formal, and I find myself using a simpler _boxes and arrows_
1551 | style for design drawings. But I'm fairly sure UML is at least as good for you
1552 | as studying Latin.
1553 | 
1554 | XML is a standard for defining new standards. It is _ not_ a solution to data
1555 | interchange problems, though you sometimes see it presented as if it was.
1556 | Rather, it is a welcome automation of the most boring part of data
1557 | interchange, namely, structuring the representation into a linear sequence and
1558 | parsing back into a structure. It provides some nice type- and correctness-
1559 | checking, though again only a fraction of what you are likely to need in
1560 | practicen.
1561 | 
1562 | SQL is a very powerful and rich data query and manipulation language that is
1563 | not quite a programming language. It has many variations, typically quite
1564 | product-dependent, which are less important than the standardized core. SQL is
1565 | the _ lingua franca_ of relational databases. You may or may not work in any
1566 | field that can benefit from an understanding of relational databases, but you
1567 | should have a basic understanding of them and they syntax and meaning of SQL.
1568 | 
1569 | ### Heavy Tools
1570 | 
1571 | As our technological culture progresses, software technology moves from
1572 | inconceivable, to research, to new products, to standardized products, to
1573 | widely available and inexpensive products. These heavy tools can pull great
1574 | loads, but can be intimidating and require a large investment in
1575 | understanding. The intermediate programmer has to know how to manage them and
1576 | when they should be used or considered.
1577 | 
1578 | To my mind right some of the best heavy tools are:
1579 | 
1580 |   * Relational Databases, 
1581 | 
1582 |   * Full-text Search Engines, 
1583 | 
1584 |   * Math libraries, 
1585 | 
1586 |   * OpenGL, 
1587 | 
1588 |   * XML parsers, and 
1589 | 
1590 |   * Spreadsheets. 
1591 | 
1592 | ### How to analyze data
1593 | 
1594 | --
1595 | 
1596 | Data analysis is a process in the early stages of software development, when
1597 | you examine a business activity and find the requirements to convert it into a
1598 | software application. This is a formal definition, which may lead you to
1599 | believe that data analysis is an action that you should better leave to the
1600 | systems analysts, while you, the programmer, should focus on coding what
1601 | somebody else has designed. If we follow strictly the software engineering
1602 | paradigm, it may be correct. Experienced programmers become designers and the
1603 | sharpest designers become business analysts, thus being entitled to think
1604 | about all the data requirements and give you a well defined task to carry out.
1605 | This is not entirely accurate, because data is the core value of every
1606 | programming activity. Whatever you do in your programs, you are either moving
1607 | around or modifying data. The business analyst is analyzing the needs in a
1608 | larger scale, and the software designer is further squeezing such scale so
1609 | that, when the problem lands on your desk, it seems that all you need to do is
1610 | to apply clever algorithms and start moving existing data.
1611 | 
1612 | Not so.
1613 | 
1614 | No matter at which stage you start looking at it, data is the main concern of
1615 | a well designed application. If you look closely at how a business analyst
1616 | gets the requirements out of the customer?s requests, you?ll realize that data
1617 | plays a fundamental role. The analyst creates so called Data Flow Diagrams,
1618 | where all data sources are identified and the flow of information is shaped.
1619 | Having clearly defined which data should be part of the system, the designer
1620 | will shape up the data sources, in terms of database relations, data exchange
1621 | protocols, and file formats, so that the task is ready to be passed down to
1622 | the programmer. However, the process is not over yet, because you ? the
1623 | programmer ? even after this thorough process of data refinement, are required
1624 | to analyze data to perform the task in the best possible way. The bottom line
1625 | of your task is the core message of Niklaus Wirth, the father of several
1626 | languages. ?Algorithms + Data Structures = Programs.? There is never an
1627 | algorithm standing alone, doing something to itself. Every algorithm is
1628 | supposed to do something to at least one piece of data.
1629 | 
1630 | Therefore, since algorithms don't spin their wheels in a vacuum, you need to
1631 | analyze both the data that somebody else has identified for you and the data
1632 | that is necessary to write down your code. A trivial example will make the
1633 | matter clearer. You are implementing a search routine for a library. According
1634 | to your specifications, the user can select books by a combination of genre,
1635 | author, title, publisher, printing year, and number of pages. The ultimate
1636 | goal of your routine is to produce a legal SQL statement to search the back-
1637 | end database. Based on these requirements, you have several choices: check
1638 | each control in turn, using a "switch" statement, or several "if" ones; make
1639 | an array of data controls, checking each element to see if it is set; create
1640 | (or use) an abstract control object from which inherit all your specific
1641 | controls, and connect them to an event-driven engine. If your requirements
1642 | include also tuning up the query performance, by making sure that the items
1643 | are checked in a specific order, you may consider using a tree of components
1644 | to build your SQL statement. As you can see, the choice of the algorithm
1645 | depends on the data you decide to use, or to create. Such decisions can make
1646 | all the difference between an efficient algorithm and a disastrous one.
1647 | However, efficiency is not the only concern. You may use a dozen named
1648 | variables in your code and make it as efficient as it can ever be. But such a
1649 | piece of code might not be easily maintainable. Perhaps choosing an
1650 | appropriate container for your variables could keep the same speed and in
1651 | addition allow your colleagues to understand the code better when they look at
1652 | it next year. Furthermore, choosing a well defined data structure may allow
1653 | them to extend the functionality of your code without rewriting it. In the
1654 | long run, your choices of data determines how long your code will survive
1655 | after you are finished with it. Let me give you another example, just some
1656 | more food for thought. Let's suppose that your task is to find all the words
1657 | in a dictionary with more than three anagrams, where an anagram must be
1658 | another word in the same dictionary. If you think of it as a computational
1659 | task, you will end up with an endless effort, trying to work out all the
1660 | combinations of each word and then comparing it to the other words in the
1661 | list. However, if you analyze the data at hand, you'll realize that each word
1662 | may be represented by a record containing the word itself and a sorted array
1663 | of its letters as ID. Armed with such knowledge, finding anagrams means just
1664 | sorting the list on the additional field and picking up the ones that share
1665 | the same ID. The brute force algorithm may take several days to run, while the
1666 | smart one is just a matter of a few seconds. Remember this example the next
1667 | time you are facing an intractable problem.
1668 | 
1669 | ## Team Skills
1670 | 
1671 | ### How to Manage Development Time
1672 | 
1673 | To manage development time, maintain a concise and up-to-date project plan. A
1674 | project plan is an estimate, a schedule, a set of milestones for marking
1675 | progress, and an assignment of your team or your own time to each task on the
1676 | estimate. It should also include other things you have to remember to do, such
1677 | as meeting with the quality assurance people, preparing documentation, or
1678 | ordering equipment. If you are on a team, the project plan should be a
1679 | consensual agreement, both at the start and as you go.
1680 | 
1681 | The project plan exists to help make decisions, not to show how organized you
1682 | are. If the project plan is either too long or not up-to-date, it will be
1683 | useless for making decisions. In reality, these decisions are about individual
1684 | persons. The plan and your judgment let you decide if you should shift tasks
1685 | from one person to another. The milestones mark your progress. If you use a
1686 | fancy project planning tool, do not be seduced into creating a Big Design Up
1687 | Front (BDUF) for the project, but use it maintain concision and up-to-
1688 | dateness.
1689 | 
1690 | If you miss a milestone, you should take immediate action such as informing
1691 | your boss that the scheduled completion of that project has slipped by that
1692 | amount. The estimate and schedule could never have been perfect to begin with;
1693 | this creates the illusion that you might be able to make up the days you
1694 | missed in the latter part of the project. You might. But it is just as likely
1695 | that you have underestimated that part as that you have overestimated it.
1696 | Therefore the scheduled completion of the project has already slipped, whether
1697 | you like it or not.
1698 | 
1699 | Make sure you plan includes time for: internal team meetings, demos,
1700 | documentation, scheduled periodic activities, integration testing, dealing
1701 | with outsiders, sickness, vacations, maintenance of existing products, and
1702 | maintenance of the development environment. The project plan can serve as a
1703 | way to give outsiders or your boss a view into what you or your team is doing.
1704 | For this reason it should be short and up-to-date.
1705 | 
1706 | ### How to Manage Third-Party Software Risks
1707 | 
1708 | A project often depends on software produced by organizations that it does not
1709 | control. There are great risks associated with third party software that must
1710 | be recognized by everyone involved.
1711 | 
1712 | Never, ever, rest any hopes on _ vapor_. _ Vapor_ is any alleged software that
1713 | has been promised but is not yet available. This is the surest way to go out
1714 | of business. It is unwise to be merely skeptical of a software company's
1715 | promise to release a certain product with a certain feature at a certain date;
1716 | it is far wiser to ignore it completely and forget you ever heard it. Never
1717 | let it be written down in any documents used by your company.
1718 | 
1719 | If third-party software is not vapor, it is still risky, but at least it is a
1720 | risk that can be tackled. If you are considering using third-party software,
1721 | you should devote energy early on to evaluating it. People might not like to
1722 | hear that it will take two weeks or two months to evaluate each of three
1723 | products for suitability, but it has to be done as early as possible. The cost
1724 | of integrating cannot be accurately estimated without a proper evaluation.
1725 | 
1726 | Understanding the suitability of existing third party software for a
1727 | particular purpose is very tribal knowledge. It is very subjective and
1728 | generally resides in experts. You can save a lot of time if you can find those
1729 | experts. Often times a project will depend on a third-party software system so
1730 | completely that if the integration fails the project will fail. Express risks
1731 | like that clearly in writing in the schedule. Try to have a contingency plan,
1732 | such as another system that can be used or the ability to write the
1733 | functionality yourself if the risk can't be removed early. Never let a
1734 | schedule depend on vapor.
1735 | 
1736 | ### How to Manage Consultants
1737 | 
1738 | Use consultants, but don't rely on them. They are wonderful people and deserve
1739 | a great deal of respect. Since they get to see a lot of different projects,
1740 | they often know more about specific technologies and even programming
1741 | techniques than you will. The best way to use them is as educators in-house
1742 | that can teach by example.
1743 | 
1744 | However, they usually cannot become part of the team in the same sense that
1745 | regular employees are, if only because you may not have enough time to learn
1746 | their strengths and weaknesses. Their financial commitment is much lower. They
1747 | can move more easily. They may have less to gain if the company does well.
1748 | Some will be good, some will be average, and some will be bad, but hopefully
1749 | your selection of consultants will not be as careful as your selection of
1750 | employees, so you will get more bad ones.
1751 | 
1752 | If consultants are going to write code, you must review it carefully as you go
1753 | along. You cannot get to the end of the a project with the risk of a large
1754 | block of code that has not been reviewed. This is true of all team members,
1755 | really, but you will usually have more knowledge of the team members closer to
1756 | you.
1757 | 
1758 | ### How to Communicate the Right Amount
1759 | 
1760 | Carefully consider the cost of a meeting; it costs _ its duration multiplied
1761 | by the number of participants_. Meetings are sometimes necessary, but smaller
1762 | is usually better. The quality of communication in small meetings is better,
1763 | and less time overall is wasted. If any one person is bored at a meeting take
1764 | this as a sing, that the meeting should be smaller.
1765 | 
1766 | Everything possible should be done to encourage informal communication. More
1767 | useful work is done during lunches with colleagues than during any other time.
1768 | It is a shame that more companies do not recognize nor support this fact.
1769 | 
1770 | ### How to Disagree Honestly and Get Away with It
1771 | 
1772 | Disagreement is a great opportunity to make a good decision, but it should be
1773 | handled delicately. Hopefully you feel that you have expressed your thoughts
1774 | adequately and been heard before the decision is made. In that case there is
1775 | nothing more to say, and you should decide whether you will stand behind the
1776 | decision even though you disagree with it. If you can support this decision
1777 | even though you disagree, say so. This shows how valuable you are because you
1778 | are independent and are not a yes-man, but respectful of the decision and a
1779 | team player.
1780 | 
1781 | Sometimes a decision that you disagree with will be made when the decision
1782 | makers did not have the full benefit of you opinion. You should then evaluate
1783 | whether to raise the issue on the basis of the benefit to the company or
1784 | tribe. If it is a small mistake in your opinion, it may not be worth
1785 | reconsidering. If it is a large mistake in you opinion, then of course you
1786 | must present an argument.
1787 | 
1788 | Usually, this is not a problem. In some stressful circumstances and with some
1789 | personality types this can lead to things being taken personally. For
1790 | instance, some very good programmers lack the confidence needed to challenge a
1791 | decision even when they have good reason to believe it is wrong. In the worst
1792 | of circumstances the decision maker is insecure and takes it as a personal
1793 | challenge to their authority. It is best to remember that in such
1794 | circumstances people react with the reptilian part of their brains. You should
1795 | present your argument in private, and try to show how new knowledge changes
1796 | the basis on which the decision was made.
1797 | 
1798 | Whether the decision is reversed or not, you must remember that you will never
1799 | be able to say 'I told you so!' since the alternate decision was fully
1800 | explored.
1801 | 
1802 | ## Judgement
1803 | 
1804 | ### How to Tradeoff Quality Against Development Time
1805 | 
1806 | Software development is always a compromise between what the project does and
1807 | getting the project done. But you may be asked to tradeoff quality to speed
1808 | the deployment of a project in a way that offends your engineering
1809 | sensibilities or business sensibilities. For example, you may be asked to do
1810 | something that is a poor software engineering practice and that will lead to a
1811 | lot of maintenance problems.
1812 | 
1813 | If this happens your first responsibility is to inform your team and to
1814 | clearly explain the cost of the decrease in quality. After all, your
1815 | understanding of it should be much better than your boss's understanding. Make
1816 | it clear what is being lost and what is being gained, and at what cost the
1817 | lost ground will be regained in the next cycle. In this, the visibility
1818 | provided by a good project plan should be helpful. If the quality tradeoff
1819 | affects the quality assurance effort, point that out (both to your boss and
1820 | quality assurance people). If the quality tradeoff will lead to more bugs
1821 | being reported after the quality assurance period, point that out.
1822 | 
1823 | If she still insists you should try to isolate the shoddiness into particular
1824 | components that you can plan to rewrite or improve in the next cycle. Explain
1825 | this to your team so that they can plan for it.
1826 | 
1827 | NinjaProgrammer at Slashdot sent in this gem:
1828 | 
1829 | > Remember that a good _ design_ will be resillient against poor code
1830 | implementations. If good interfaces and abstractions exist throughout the
1831 | code, then the eventual rewrites will be far more painless. If it is hard to
1832 | write clear code that is hard to fix, consider what is wrong with the core
1833 | design that is causing this.
1834 | 
1835 | ### How to Manage Software System Dependence
1836 | 
1837 | Modern software systems tend to depend on a large number of components that
1838 | may not be directly under your control. This increases productivity through
1839 | synergy and reuse. However, each component brings with it some problems:
1840 | 
1841 |   * How will you fix bugs in the component? 
1842 | 
1843 |   * Does the component restrict you to particular hardware or software systems? 
1844 | 
1845 |   * What will you do if the component fails completely? 
1846 | 
1847 | It is always best to encapsulate the component in some way so that it is
1848 | isolated and so that it can be swapped out. If the component proves to be
1849 | completely unworkable, you may be able to get a different one, but you may
1850 | have to write your own. Encapsulation is not portability, but it makes porting
1851 | easier, which is almost as good.
1852 | 
1853 | Having the source code for a component decreases the risk by a factor of four.
1854 | With source code, you can evaluate it easier, debug it easier, find
1855 | workarounds easier, and make fixes easier. If you make fixes, you should give
1856 | them to the owner of the component and get the fixes incorporated into an
1857 | official release; otherwise you will uncomfortably have to maintain an
1858 | unofficial version .
1859 | 
1860 | ### How to Decide if Software is Too Immature
1861 | 
1862 | Using software other people wrote is one of the most effective ways to quickly
1863 | build a solid system. It should not be discouraged, but the risks associated
1864 | with it must be examined. One of the biggest risks is the period of bugginess
1865 | and near inoperability that is often associated with software before it
1866 | matures, through usage, into a usable product. Before you consider integrating
1867 | with a software system, whether created in house or by a third party, it is
1868 | very important to consider if it is really mature enough to be used. Here are
1869 | ten questions you should ask yourself about it:
1870 | 
1871 |   1. Is it vapor? (Promises are very immature). 
1872 | 
1873 |   2. Is there an accessible body of lore about the software? 
1874 | 
1875 |   3. Are you the first user? 
1876 | 
1877 |   4. Is there a strong incentive for continuation? 
1878 | 
1879 |   5. Has it had a maintenance effort? 
1880 | 
1881 |   6. Will it survive defection of the current maintainers? 
1882 | 
1883 |   7. Is there a seasoned alternative at least half as good? 
1884 | 
1885 |   8. Is it known to your tribe or company? 
1886 | 
1887 |   9. Is it desirable to your tribe or company? 
1888 | 
1889 |   10. Can you hire people to work on it even if it is bad? 
1890 | 
1891 | A little consideration of these criteria demonstrates the great value of well-
1892 | established free software and open-source software in reducing risk to the
1893 | entrepreneur.
1894 | 
1895 | ### How to Make a Buy vs. Build Decision
1896 | 
1897 | An entrepreneurial company or project that is trying to accomplish something
1898 | with software has to constantly make so-called _ buy vs. build_ decisions.
1899 | This turn of phrase is unfortunate in two ways: it seems to ignore open-source
1900 | and free software which is not necessarily _ bought_. Even more importantly,
1901 | it should perhaps be called an _ obtain and integrate_ vs. _ build here and
1902 | integrate_ decision because the cost of integration must be considered. This
1903 | requires a great combination of business, management, and engineering savvy.
1904 | 
1905 |   * How well do your needs match those for which it was designed? 
1906 | 
1907 |   * What portion of what you buy will you need? 
1908 | 
1909 |   * What is the cost of evaluating the integration? 
1910 | 
1911 |   * What is the cost of integration? 
1912 | 
1913 |   * What is the cost of evaluating the integration? 
1914 | 
1915 |   * Will buying increase or decrease long term maintenance costs? 
1916 | 
1917 |   * Will building it put you in a business position you don't want to be in? 
1918 | 
1919 | You should think twice before building something that is big enough to serve
1920 | as the basis for an entire other business. Such ideas are often proposed by
1921 | bright and optimistic people that will have a lot to contribute to your team.
1922 | If their idea is compelling, you may wish to change your business plan; but do
1923 | not invest in a solution bigger than your own business without conscious
1924 | thought.
1925 | 
1926 | After considering these questions, you should perhaps prepare two draft
1927 | project plans, one for building and one for buying. This will force you to
1928 | consider the integration costs. You should also consider the long term
1929 | maintenance costs of both solutions. To estimate the integration costs, you
1930 | will have to do a thorough evaluation of the software before you buy it. If
1931 | you can't evaluate it, you will assume an unreasonable risk in buying it and
1932 | you should decide against buying that particular product. If there are several
1933 | buy decisions under consideration, some energy will have to be spent
1934 | evaluating each.
1935 | 
1936 | ### How to Grow Professionally
1937 | 
1938 | Assume responsibility in excess of your authority. Play the role that you
1939 | desire. Express appreciation for people's contribution to the success of the
1940 | larger organization, as well as things as that help you personally.
1941 | 
1942 | If you want to become a team leader, instigate the formation of consensus. If
1943 | you want to become a manager, take responsibility for the schedule. You can
1944 | usually do this comfortably while working with a leader or a manager, since
1945 | this frees them up to take greater responsibility. If that is too much to try,
1946 | do it a little at a time.
1947 | 
1948 | Evaluate yourself. If you want to become a better programmer, ask someone you
1949 | admire how you can become like them. You can also ask your boss, who will know
1950 | less but have a greater impact on your career.
1951 | 
1952 | Plan ways to learn new skills, both the trivial technical kind, like learning
1953 | a new software system, and the hard social kind, like writing well, by
1954 | integrating them into your work.
1955 | 
1956 | ### How to Evaluate Interviewees
1957 | 
1958 | Evaluating potential employees is not given the energy it deserves. A bad
1959 | hire, like a bad marriage, is terrible. A significant portion of everyone's
1960 | energy should be devoted to recruitment, though this is rarely done.
1961 | 
1962 | There are different interviewing styles. Some are torturous, designed to put
1963 | the candidate under a great deal of stress. This serves a very valuable
1964 | purpose of possibly revealing character flaws and weaknesses under stress.
1965 | Candidates are no more honest with interviewers than they are with themselves,
1966 | and the human capacity for self-deception is astonishing.
1967 | 
1968 | You should, at a minimum, give the candidate the equivalent of an oral
1969 | examination on the technical skills for two hours. With practice, you will be
1970 | able to quickly cover what they know and quickly retract from what they don't
1971 | know to mark out the boundary. Interviewees will respect this. I have several
1972 | times heard interviewees say that the quality of the examination was one of
1973 | their motivations for choosing a company. Good people want to be hired for
1974 | their skills, not where they worked last or what school they went to or some
1975 | other inessential characteristic.
1976 | 
1977 | In doing this, you should also evaluate their ability to learn, which is far
1978 | more important than what they know. You should also watch for the whiff of
1979 | brimstone that is given off by difficult people. You may be able to recognize
1980 | it by comparing notes after the interview, but in the heat of the interview it
1981 | is hard to recognize. How well people communicate and work with people is more
1982 | important than being up on the latest programming language.
1983 | 
1984 | A reader has had good luck using a 'take-home' test for interviewees. This has
1985 | the advantage that can uncover the interviewee that can present themselves
1986 | well but can't really code---and there are many such people. I personally have
1987 | not tried this technique, but it sounds sensible.
1988 | 
1989 | Finally, interviewing is also a process of selling. You should be selling your
1990 | company or project to the candidate. However, you are talking to a programmer,
1991 | so don't try to color the truth. Start off with the bad stuff, then finish
1992 | strong with the good stuff.
1993 | 
1994 | ### How to Know When to Apply Fancy Computer Science
1995 | 
1996 | There is a body of knowledge about algorithms, data structures, mathematics,
1997 | and other gee-whiz stuff that most programmers know about but rarely use. In
1998 | practice, this wonderful stuff is too complicated and generally unnecessary.
1999 | There is no point in improving an algorithm when most of your time is spent
2000 | making inefficient database calls, for instance. An unfortunate amount of
2001 | programming consists of getting systems to talk to each other and using very
2002 | simple data structures to build a nice user interface.
2003 | 
2004 | When is high technology the appropriate technology? When should you crack a
2005 | book to get something other than a run-of-the-mill algorithm? It is sometimes
2006 | useful to do this but it should be evaluated carefully.
2007 | 
2008 | The three most important considerations for the potential computer science
2009 | technique are:
2010 | 
2011 |   * Is it well encapsulated so that the risk to other systems is low and the overall increase in complexity and maintenance cost is low? 
2012 | 
2013 |   * Is the benefit startling (for example, a factor of two in a mature system or a factor of ten in a new system)? 
2014 | 
2015 |   * Will you be able to test and evaluate it effectively? 
2016 | 
2017 | If a well-isolated algorithm that uses a slightly fancy algorithm can decrease
2018 | hardware cost or increase performance by a factor of two across an entire
2019 | system, then it would be criminal not to consider it. One of the keys to
2020 | arguing for such an approach is to show that the risk is really quite low,
2021 | since the proposed technology has probably been well studied, the only issue
2022 | is the risk of integration. Here a programmer's experience and judgment can
2023 | truly synergize with the fancy technology to make integration easy.
2024 | 
2025 | ### How to Talk to Non-Engineers
2026 | 
2027 | Engineers and programmers in particular are generally recognized by popular
2028 | culture as being different from other people. This implies that other people
2029 | are different from us. This is worth bearing in mind when communicating with
2030 | non-engineers; you should always understand the audience.
2031 | 
2032 | Non-engineers are smart, but not as grounded in creating technical things as
2033 | we are. We make things. They sell things and handle things and count things
2034 | and manage things, but they are not experts on making things. They are not as
2035 | good at working together on teams as engineers are (there are no doubt
2036 | exceptions.)[3] Their social skills are generally as good as or better than
2037 | engineers in non-team environments, but their work does not always demand that
2038 | they practice the kind of intimate, precise communication and careful
2039 | subdivisions of tasks that we do.
2040 | 
2041 | Non-engineers may be too eager to please and they may be intimidated by you.
2042 | Just like us, they may say 'yes' without really meaning it to please you or
2043 | because they are a little scared of you, and then not stand behind their
2044 | words.
2045 | 
2046 | Non-programmers can understand technical things but they do not have the thing
2047 | that is so hard even for us---technical judgment. They do understand how
2048 | technology works, but they cannot understand why a certain approach would take
2049 | three months and another one three days. (After all, programmers are
2050 | anecdotally horrible at this kind of estimation as well.) This represents a
2051 | great opportunity to synergize with them.
2052 | 
2053 | When talking to your team you will, without thinking, use a sort of shorthand,
2054 | an abbreviated language that is effective because you will have much shared
2055 | experience about technology in general and your product in particular. It
2056 | takes some effort not to use this shorthand with those that don't have that
2057 | shared experience, especially when members of your own team are present. This
2058 | vocabulary create a wall between you and those that do not share it, and, even
2059 | worse, wastes their time.
2060 | 
2061 | With your team, the basic assumptions and goals do not need to be restated
2062 | often, and most conversation focuses on the details. With outsiders, it must
2063 | be the other way around. They may not understand things you take for granted.
2064 | Since you take them for granted and don't repeat them, you can leave a
2065 | conversation with an outsider thinking that you understand each other when
2066 | really there is a large misunderstanding. You should assume that you will
2067 | miscommunicate and watch carefully to find this miscommunication. Try to get
2068 | them to summarize or paraphrase what you are saying to make sure they
2069 | understand. If you have the opportunity to meet with them often, spend a
2070 | little bit of time asking if you you are communicating effectively, and how
2071 | you can do it better. If there is a problem in communication, seek to alter
2072 | your own practices before becoming frustrated with theirs.
2073 | 
2074 | I love working with non-engineers. It provides great opportunities to learn
2075 | and to teach. You can often lead by example, in terms of the clarity of your
2076 | communication. Engineers are trained to bring order out of chaos, to bring
2077 | clarity out of confusion, and non-engineers like this about us. Because we
2078 | have technical judgment and can usually understand business issues, we can
2079 | often find a simple solution to a problem.
2080 | 
2081 | Often non-engineers propose solutions that they think will make it easier on
2082 | us out of kindness and a desire to do the right thing, when in fact a much
2083 | better overall solution exists which can only be seen by synergizing the
2084 | outsiders view with your technical judgment. I personally like Extreme
2085 | Programming because it addresses this inefficiency; by marrying the estimation
2086 | quickly to the idea, it makes it easier to find the idea that is the best
2087 | combination of cost and benefit.
2088 | 
2089 |   
2090 | 
2091 | * * *
2092 | 
2093 | [1] "to hit"
2094 | 
2095 | ## Chapter 4. Advanced
2096 | 
2097 | **Table of Contents**
2098 | 
2099 | Technological Judgment
2100 | 
2101 |     
2102 | 
2103 | How to Tell the Hard From the Impossible
2104 | 
2105 | How to Utilize Embedded Languages
2106 | 
2107 | Choosing Languages
2108 | 
2109 | Compromising Wisely
2110 | 
2111 |     
2112 | 
2113 | How to Fight Schedule Pressure
2114 | 
2115 | How to Understand the User
2116 | 
2117 | How to Get a Promotion
2118 | 
2119 | Serving Your Team
2120 | 
2121 |     
2122 | 
2123 | How to Develop Talent
2124 | 
2125 | How to Choose What to Work On
2126 | 
2127 | How to Get the Most From Your Teammates
2128 | 
2129 | How to Divide Problems Up
2130 | 
2131 | How to Handle Boring Tasks
2132 | 
2133 | How to Gather Support for a Project
2134 | 
2135 | How to Grow a System
2136 | 
2137 | How to Communicate Well
2138 | 
2139 | How to Tell People Things They Don't Want to Hear
2140 | 
2141 | How to Deal with Managerial Myths
2142 | 
2143 | How to Deal with Organizational Chaos
2144 | 
2145 | ## Technological Judgment
2146 | 
2147 | ### How to Tell the Hard From the Impossible
2148 | 
2149 | It is our job to do the hard and discern the impossible. From the point of
2150 | view of most working programmers, something is impossible if either it cannot
2151 | be grown from a simple system or it cannot be estimated. By this definition
2152 | what is called research is impossible. A large volume of _ mere work_ is hard,
2153 | but not necessarily impossible.
2154 | 
2155 | The distinction is not facetious because you may very well be asked to do what
2156 | is practically impossible, either from a scientific point of view or a
2157 | software engineering point of view. It then becomes your job to help the
2158 | entrepreneur find a reasonable solution which is _ merely hard_ and gets most
2159 | of what they wanted. A solution is merely hard when it can be confidently
2160 | scheduled and the risks are understood.
2161 | 
2162 | It is impossible to satisfy a vague requirement, such as 'Build a system that
2163 | will compute the most attractive hair style and color for any person.' If the
2164 | requirement can be made more crisp, it will often become merely hard, such as
2165 | 'Build a system to compute an attractive hair style and color for a person,
2166 | allow them to preview it and make changes, and have the customer satisfaction
2167 | based on the original styling be so great that we make a lot of money.' If
2168 | there is not crisp definition of success, you will not succeed.
2169 | 
2170 | ### How to Utilize Embedded Languages
2171 | 
2172 | Embedding a programming language into a system has an almost erotic
2173 | fascination to a programmer. It is one of the most creative acts that can be
2174 | performed. It makes the system tremendously powerful. It allows you to
2175 | exercise her most creative and Promethean skills. It makes the system into
2176 | your friend.
2177 | 
2178 | The best text editors in the world all have embedded languages. This can be
2179 | used to the extent that the intended audience can master the language. Of
2180 | course, use of the language can be made optional, as it is in text editors, so
2181 | that initiates can use it and no one else has to.
2182 | 
2183 | I and many other programmers have fallen into the trap of creating special
2184 | purpose embedded languages. I fell into it twice. There already exist many
2185 | languages designed specifically to be embedded languages. You should think
2186 | twice before creating a new one.
2187 | 
2188 | The real question to ask oneself before embedding a language is: Does this
2189 | work with or against the culture of my audience? If you intended audience is
2190 | exclusively non-programmers, how will it help? If your intended audience is
2191 | exclusively programmers, would they prefer an applications programmers
2192 | interface (API)? And what language will it be? Programmers don't want to learn
2193 | a new language that is narrowly used; but if it meshes with their culture they
2194 | will not have to spend much time learning it. It is a joy to create a new
2195 | language. But we should not let that blind us to the needs of the user. Unless
2196 | you have some truly original needs and ideas, why not use an existing language
2197 | so that you can leverage the familiarity users already have with it?
2198 | 
2199 | ### Choosing Languages
2200 | 
2201 | The solitary programmer that loves his work (a hacker) can choose the best
2202 | language for the task. Most working programmers have very little control of
2203 | the language they will use. Generally, this issue is dictated by pointy-haired
2204 | bosses who are making a political decision, rather than a technological
2205 | decision, and lack the courage to promote an unconventional tool even when
2206 | they know, often with firsthand knowledge, that the less accepted tool is
2207 | best. In other cases the very real benefit of unity among the team, and to
2208 | some extent with a larger community, precludes choice on the part of the
2209 | individual. Often managers are driven by the need to be able to hire
2210 | programmers with experience in a given language. No doubt they are serving
2211 | what they perceive to be the best interests of the project or company, and
2212 | must be respected for that. However, I personally believe this the most
2213 | wasteful and erroneous common practice you are likely to encounter.
2214 | 
2215 | But of course, things are never one-dimensional. Even if a core language is
2216 | mandated and beyond your control, it is often the case that tools and other
2217 | programs can and should be written in a different language. If a language is
2218 | to be embedded (and you should always consider it!) the choice of language
2219 | will depend a lot on the culture of the users. One should take advantage of
2220 | this to serve your company or project by using the best language for the job,
2221 | and in so doing make work more interesting.
2222 | 
2223 | Programming languages should really be called _ notations_ in that learning
2224 | one is not at all as difficult as learning a natural language. To beginners
2225 | and to some outsiders ``learning a new language'' seems a daunting task; but
2226 | after you have three under your belt it's really just a question of becoming
2227 | familiar with the available libraries. One tends to think of a large system
2228 | that has components in three or four languages as a messy hodgepodge; but I
2229 | argue that such a system is in many cases stronger than a one-language system
2230 | in several ways:
2231 | 
2232 |   * There is necessarily loose coupling between the components that are written in different notations (though maybe not clean interfaces), 
2233 | 
2234 |   * You can evolve to a new language/platform easily by rewriting each component individually, 
2235 | 
2236 |   * Its possible that some of the modules are actually up-to-date. 
2237 | 
2238 | Some of these effects may only be psychological; but psychology matters. In
2239 | the end the costs of language tyranny outweigh any advantage that it provides.
2240 | 
2241 | ## Compromising Wisely
2242 | 
2243 | ### How to Fight Schedule Pressure
2244 | 
2245 | Time-to-market pressure is the pressure to deliver a good product quickly. It
2246 | is good because it reflects a financial reality, and is healthy up to a point.
2247 | Schedule pressure is the pressure to deliver something faster than it can be
2248 | delivered and it is wasteful, unhealthy, and all too common.
2249 | 
2250 | Schedule pressure exists for several reasons. The people who task programmers
2251 | do not fully appreciate what a strong work ethic we have and how much fun it
2252 | is to be a programmer. Perhaps because they project their own behavior onto
2253 | us, they believe that asking for it sooner will make us work harder to get it
2254 | there sooner. This is probably actually true, but the effect is very small,
2255 | and the damage is very great. Additionally, they have no visibility into what
2256 | it really takes to produce software. Not being able to see it, and not be able
2257 | to create it themselves, the only thing they can do is see time-to-market
2258 | pressure and fuss at programmers about it.
2259 | 
2260 | The key to fighting schedule pressure is simply to turn it into time-to-market
2261 | pressure. The way to do this to give visibility into the relationship between
2262 | the available labor and the product. Producing an honest, detailed, and most
2263 | of all, _understandable_ estimate of all the labor involved is the best way to
2264 | do this. It has the added advantage of allowing good management decisions to
2265 | be made about possible functionality tradeoffs.
2266 | 
2267 | The key insight that the estimate must make plain is that labor is an almost
2268 | incompressible fluid. You can't pack more into a span of time anymore than you
2269 | can pack more water into a container over and above that container's volume.
2270 | In a sense, a programmer should never say 'no', but rather to say 'What will
2271 | you give up to get that thing you want?' The effect of producing clear
2272 | estimates will be to increase the respect for programmers. This is how other
2273 | professionals behave. Programmers' hard work will be visible. Setting an
2274 | unrealistic schedule will also be painfully obvious to everyone. Programmers
2275 | cannot be hoodwinked. It is disrespectful and demoralizing to ask them to do
2276 | something unrealistic. Extreme Programming amplifies this and builds a process
2277 | around it; I hope that every reader will be lucky enough to use it.
2278 | 
2279 | ### How to Understand the User
2280 | 
2281 | It is your duty to understand the user, and to help your boss understand the
2282 | user. Because the user is not as intimately involved in the creation of your
2283 | product as you are, they behave a little differently:
2284 | 
2285 |   * The user generally makes short pronouncements. 
2286 | 
2287 |   * The user has their own job; they will mainly think of small improvements in your product, not big improvements. 
2288 | 
2289 |   * The user can't have a vision that represents the complete body of your product users. 
2290 | 
2291 | It is your duty to give them what they really want, not what they say they
2292 | want. It is however, better to propose it to them and get them to agree that
2293 | your proposal is what they really want before you begin, but they may not have
2294 | the vision to do this. Your confidence in your own ideas about this should
2295 | vary. You must guard against both arrogance and false modesty in terms of
2296 | knowing what the customer really wants. Programmers are trained to design and
2297 | create. Market researchers are trained to figure out what people want. These
2298 | two kinds of people, or two modes of thought in the same person, working
2299 | harmoniously together give the best chance of formulating the correct vision.
2300 | 
2301 | The more time you spend with users the better you will be able to understand
2302 | what will really be successful. You should try to test your ideas against them
2303 | as much as you can. You should eat and drink with them if you can.
2304 | 
2305 | Guy Kawasaki[Rules] has emphasized the importance of _ watching_ what your
2306 | users do in addition to listening to them.
2307 | 
2308 | I believe contractors and consultants often have tremendous problems getting
2309 | their clients to clarify in their own minds what they really want. If you
2310 | intend to be a consultant, I suggest you choose your clients based on their
2311 | clear-headedness as well as their pocketbooks.
2312 | 
2313 | ### How to Get a Promotion
2314 | 
2315 | To be promoted to a role, act out that role first.
2316 | 
2317 | To get promoted to a title, find out what is expected of that title and do
2318 | that.
2319 | 
2320 | To get a pay raise, negotiate armed with information.
2321 | 
2322 | If you feel like you are past due for a promotion, talk to your boss about it.
2323 | Ask them explicitly what you need to do to get promoted, and try to do it.
2324 | This sounds trite, but often times your perception of what you need to do will
2325 | differ considerably from your boss's. Also this will pin your boss down in
2326 | some ways.
2327 | 
2328 | Most programmers probably have an exaggerated sense of their relative
2329 | abilities in some ways---after all, we can't all be in the top 10%! However, I
2330 | have seem some people who were seriously unappreciated. One cannot expect
2331 | everyone's evaluation to perfectly match reality at all times, but I think
2332 | people are generally moderately fair, with one caveat: you cannot be
2333 | appreciated without visibility into your work. Sometimes, do to happenstance
2334 | or personal habits, someone will not be noticed much. Working from home a lot
2335 | or being geographically separated from your team and boss makes this
2336 | especially difficult.
2337 | 
2338 | ## Serving Your Team
2339 | 
2340 | ### How to Develop Talent
2341 | 
2342 | Nietschze exaggerated when he said[Stronger]:
2343 | 
2344 | > What does not destroy me, makes me stronger.
2345 | 
2346 | Your greatest responsibility is to your team. You should know each of them
2347 | well. You should stretch your team, but not overburden them. You should
2348 | usually talk to them about the way they are being stretched. If they buy in to
2349 | it, they will be well motivated. On each project, or every other project, try
2350 | to stretch them in both a way that they suggest and a way that you think will
2351 | be good for them. Stretch them not by giving them more work, but by giving
2352 | them a new skill or better yet a new role to play on the team.
2353 | 
2354 | You should allow people (including yourself) to fail occasionally and should
2355 | plan for some failure in your schedule. If there is never any failure, there
2356 | can be no sense of adventure. If there are not occasional failures, you are
2357 | not trying hard enough. When someone fails, you should be as gentle as you can
2358 | with them while not treating them as though they had succeeded.
2359 | 
2360 | Try to get each team member to buy in and be well motivated. Ask each of them
2361 | explicitly what they need to be well-motivated if they are not. You may have
2362 | to leave them dissatisfied, but you should know what everybody desires.
2363 | 
2364 | You can't give up on someone who is intentionally not carrying their share of
2365 | the load because of low morale or dissatisfaction and just let them be slack.
2366 | You must try to get them well-motivated and productive. As long as you have
2367 | the patience, keep this up. When your patience is exhausted, fire them. You
2368 | cannot allow someone who is intentionally working below their level to remain
2369 | on the team, since it is not fair to the team.
2370 | 
2371 | Make it clear to the strong members of your team that you think they are
2372 | strong by saying so in public. Praise should be public and criticism private.
2373 | 
2374 | The strong members of the team will naturally have more difficult tasks than
2375 | the weak members of the team. This is perfectly natural and nobody will be
2376 | bothered by it as long as everyone works hard.
2377 | 
2378 | It is an odd fact that is not reflected in salaries that a good programmer is
2379 | more productive than 10 bad programmers. This creates a strange situation. It
2380 | will often be true that you could move faster if your weak programmers would
2381 | just get out of the way. If you did this you would in fact make more progress
2382 | in the short term. However, your tribe would lose some important benefits,
2383 | namely the training of the weaker members, the spreading of tribal knowledge,
2384 | and the ability to recover from the loss of the strong members. The strong
2385 | must be gentle in this regard and consider the issue from all angles.
2386 | 
2387 | You can often give the stronger team members challenging, but carefully
2388 | delineated, tasks.
2389 | 
2390 | ### How to Choose What to Work On
2391 | 
2392 | You balance your personal needs against the needs of the team in choosing what
2393 | aspect of a project to work on. You should do what you are best at, but try to
2394 | find a way to stretch yourself not by taking on more work but by exercising a
2395 | new skill. Leadership and communication skills are more important than
2396 | technical skills. If you are very strong, take on the hardest or riskiest
2397 | task, and do it as early as possible in the project to decrease risk.
2398 | 
2399 | ### How to Get the Most From Your Teammates
2400 | 
2401 | To get the most from your teammates, develop a good team spirit and try to
2402 | keep every individual both personally challenged and personally engaged.
2403 | 
2404 | To develop team spirit, corny stuff like logoized clothing and parties are
2405 | good, but not as good as personal respect. If everyone respects everyone else,
2406 | nobody will want to let anybody down. Team spirit is created when people make
2407 | sacrifices for the team and think in terms of the good of the team before
2408 | their own personal good. As a leader, you can't ask for more than you give
2409 | yourself in this respect.
2410 | 
2411 | One of the keys to team leadership is to facilitate consensus so that everyone
2412 | has buy in. This occasionally means allowing your teammates to be wrong. That
2413 | is, if it does not harm the project too much, you must let some of your team
2414 | do things their own way, based on consensus, even if you believe with great
2415 | confidence it is the wrong thing to do. When this happens, don't agree, simply
2416 | disagree openly and accept the consensus. Don't sound hurt, or like you're
2417 | being forced into it, simply state that you disagree but think the consensus
2418 | of the team is more important. This will often cause them to backtrack. Don't
2419 | insist that they go through with their initial plan if they do backtrack.
2420 | 
2421 | If there is an individual who will not consent after you have discussed the
2422 | issues from all appropriate sides, simply assert that you have to make a
2423 | decision and that is what your decision is. If there is a way to judge if your
2424 | decision will be wrong or if it is later shown to be wrong, switch as quickly
2425 | as you can and recognize the persons who were right.
2426 | 
2427 | Ask your team, both as a group and individually, what they think would create
2428 | team spirit and make for an effective team.
2429 | 
2430 | Praise frequently rather than lavishly. Especially praise those who disagree
2431 | with you when they are praiseworthy. Praise in public and criticize in
2432 | private; with one exception: sometimes growth or the correction of a fault
2433 | can't be praised without drawing embarrassing attention to the original fault,
2434 | so that growth should be praised in private.
2435 | 
2436 | ### How to Divide Problems Up
2437 | 
2438 | It's fun to take a software project and divide it up into tasks that will be
2439 | performed by individuals. This should be done early. Sometimes managers like
2440 | to think that an estimate can be made without consideration of the individuals
2441 | that will perform the work. This is impossible since the productivity of
2442 | individuals varies so widely. Who has particular knowledge about a component
2443 | also constantly changes and can have an order of magnitude effect on
2444 | performance.
2445 | 
2446 | Just as a composer considers the timbre of the instrument that will play a
2447 | part or the coach of an athletic team considers the strengths of each player,
2448 | the experienced team leader will not usually be able to separate the division
2449 | of the project into tasks from the team members to which they will be
2450 | assigned. This is part of the reason that a high-performing team should not be
2451 | broken up.
2452 | 
2453 | There is a certain danger in this given that people will become bored as they
2454 | build upon their strengths and never improve their weaknesses or learn new
2455 | skills. However, specialization is a very useful productivity tool when not
2456 | overused.
2457 | 
2458 | ### How to Handle Boring Tasks
2459 | 
2460 | Sometimes it is not possible to avoid boring tasks that are critical to the
2461 | success of the company or the project. These tasks can really hurt the morale
2462 | of those that have to do them. The best technique for dealing with this is to
2463 | invoke or promote Larry Wall's programmer's virtue of Laziness. Try to find
2464 | some way to get the computer to do the task for you or to help your teammates
2465 | do this. Working for a week on a program to do a task that will take a week to
2466 | do by hand has the great advantage of being more educational and sometimes
2467 | more repeatable.
2468 | 
2469 | If all else fails, apologize to those who have to do the boring task, but
2470 | under no circumstances allow them to do it alone. At a minimum assign a team
2471 | of two to do the work and promote healthy teamwork to get the task done.
2472 | 
2473 | ### How to Gather Support for a Project
2474 | 
2475 | To gather support for a project, create and communicate a vision that
2476 | demonstrates real value to the organization as a whole. Attempt to let others
2477 | share in your vision creation. This gives them a reason to support you and
2478 | gives you the benefit of their ideas. Individually recruit key supporters for
2479 | your project. Wherever possible, show, don't tell. If possible, construct a
2480 | prototype or a mockup to demonstrate your ideas. A prototype is always
2481 | powerful but in software it is far superior to any written description.
2482 | 
2483 | ### How to Grow a System
2484 | 
2485 | The seed of a tree contains the idea of the adult but does not fully realize
2486 | the form and potency of the adult. The embryo grows. It becomes larger. It
2487 | looks more like the adult and has more of the uses. Eventually it bears fruit.
2488 | Later, it dies and its body feeds other organisms.
2489 | 
2490 | We have the luxury of treating software like that. A bridge is not like that;
2491 | there is never a baby bridge, but merely an unfinished bridge. Bridges are a
2492 | lot simpler than software.
2493 | 
2494 | It is good to think of software as growing, because it allows us to make
2495 | useful progress before we have a perfect mental image. We can get feedback
2496 | from users and use that to correct the growth. Pruning off weak limbs is
2497 | healthful.
2498 | 
2499 | The programmer must design a finished system that can be delivered and used.
2500 | But the advanced programmer must do more. You must design a growth path that
2501 | ends in the finished system. It is your job to take a germ of an idea and
2502 | build a path that takes it as smoothly as possible into a useful artifact.
2503 | 
2504 | To do this, you must visualize the end result and communicate it in a way that
2505 | the engineering team can get excited about. But you must also communicate to
2506 | them a path that goes from wherever they are now to where they want to be with
2507 | no large leaps. The tree must stay alive the whole time; it cannot be dead at
2508 | one point and resurrected later.
2509 | 
2510 | This approach is captured in spiral development. Milestones that are never too
2511 | far apart are used to mark progress along the path. In the ultra-competitive
2512 | environment of business, it is best if the milestones can be released and make
2513 | money as early as possible, even if they are far away from a well-designed
2514 | endpoint. One of the programmer's jobs is to balance the immediate payoff
2515 | against future payoff by wisely choosing a growth path expressed in
2516 | milestones.
2517 | 
2518 | The advanced programmer has the triple responsibility of growing software,
2519 | teams, and persons.
2520 | 
2521 | A reader, Rob Hafernik, sent in this comment on this section that I can do no
2522 | better than to quote in full:
2523 | 
2524 | > I think you under-emphasize the importance here. It's not just systems, but
2525 | algorithms, user interfaces, data models, and so on. It's absolutely _ vital_
2526 | as you work on a large system to have measurable progress toward intermediate
2527 | goals. Nothing is as bad as the special horror of getting down to the end and
2528 | discovering that the whole thing just isn't going to work (look at the recent
2529 | debacle of the Voter News System). I would even go further and state it as a
2530 | law of nature: no large, complex system can be implemented from scratch, it
2531 | can _ only_ be evolved from a simple system to a complex system in a series of
2532 | intentional steps.
2533 | 
2534 | To which one can only reply _Fiat lux_!
2535 | 
2536 | ### How to Communicate Well
2537 | 
2538 | To communicate well, you have to recognize how hard it is. It is a skill unto
2539 | itself. It is made harder by the fact that the persons with whom you have to
2540 | communicate are flawed. They do not work hard at understanding you. They speak
2541 | poorly and write poorly. They are often overworked or bored, and, at a
2542 | minimum, somewhat focused on their own work rather than the larger issues you
2543 | may be addressing. One of the advantages of taking classes and practicing
2544 | writing, public speaking, and listening is that if you become good at it you
2545 | can more readily see where problems lie and how to correct them.
2546 | 
2547 | The programmer is a social animal whose survival depends on communication with
2548 | her team. The advanced programmer is a social animal whose satisfaction
2549 | depends on communication with people outside her team.
2550 | 
2551 | The programmer brings order out of chaos. One interesting way to do this is to
2552 | initiate a proposal of some kind outside the team. This can be done in a _
2553 | strawman_ or _ white-paper_ format or just verbally. This leadership has the
2554 | tremendous advantage of setting the terms of the debate. It also exposes you
2555 | to criticism, and worse, rejection and neglect. The advanced programmer must
2556 | be prepared to accept this, because she has a unique power and therefore a
2557 | unique responsibility. Entrepreneurs who are not programmers need programmers
2558 | to provide leadership in some ways. Programmers are the part of the bridge
2559 | between ideas and reality that rests on reality.
2560 | 
2561 | I haven't mastered communicating well, but what I'm currently trying is what I
2562 | think of a four-pronged approach: After I have my ideas in order and am fully
2563 | prepared, I try to speak verbally, hand people a white-paper (on real paper,
2564 | as well as electronically) show them a demo, and then patiently repeat this
2565 | process. I think a lot of times we are not patient enough in this kind of
2566 | difficult communication. You should not be disheartened if your ideas are not
2567 | immediately accepted. If you have invested energy in there preparation, no one
2568 | will think poorly of you for it.
2569 | 
2570 | ### How to Tell People Things They Don't Want to Hear
2571 | 
2572 | You will often have to tell people things that will make them uncomfortable.
2573 | Remember that you are doing this for a reason. Even if nothing can be done
2574 | about the problem, you are telling them as early as possible so they will be
2575 | well-informed.
2576 | 
2577 | The best way to tell someone about a problem is to offer a solution at the
2578 | same time. The second best way is to appeal to them for help with the problem.
2579 | If there is a danger that you won't be believed, you should gather some
2580 | support for your assertion.
2581 | 
2582 | One of the most unpleasant and common things you will have to say is, 'The
2583 | schedule will have to slip.' The conscientious programmer hates to say this,
2584 | but must say it as early as possible. There is nothing worse than postponing
2585 | action when a milestone slips, even if the only action is to inform everyone.
2586 | In doing this, it is better to do it as a team, at least in spirit, if not
2587 | physically. You will want your team's input on both where you stand and what
2588 | can be done about it, and the team will have to face the consequences with
2589 | you.
2590 | 
2591 | ### How to Deal with Managerial Myths
2592 | 
2593 | The word _ myth_ sometimes means fiction. But it has a deeper connotation. It
2594 | also means a story of religious significance that explains the universe and
2595 | mankind's relationship to it. Managers tend to forget what they learned as
2596 | programmers and believe in certain myths. It would be as rude and unsuccessful
2597 | to try to convince them these myths are false as to try to disillusion a
2598 | devoutly religious person of their beliefs. For that reason, you should
2599 | recognize these beliefs as myths:
2600 | 
2601 |   * More documentation is always better. (They want it, but they don't want you to spend any time on it.) 
2602 | 
2603 |   * Programmers can be equated. (Programmers vary by an order of magnitude.) 
2604 | 
2605 |   * Resources can be added to a late project to speed it. (The cost of communication with the new persons is almost always more taxing than helpful.) 
2606 | 
2607 |   * It is possible to estimate software development reliably. (It is not even theoretically possible.) 
2608 | 
2609 |   * Programmers' productivity can be measured in terms of some simple metric, like lines of code. (If succinctness is power, lines of code are bad, not good.) 
2610 | 
2611 | If you have an opportunity, you can try to explain these things, but don't
2612 | feel bad if you have no success and don't damage your reputation by
2613 | confronting these myths belligerently. Each of these myths reinforces the
2614 | manager's idea that they have some actual control over what is going on. The
2615 | truth is that managers facilitate if they are good, and impede if they are
2616 | bad.
2617 | 
2618 | ### How to Deal with Organizational Chaos
2619 | 
2620 | There are often brief periods of great organizational chaos, such as layoffs,
2621 | buyouts, ipos, firings, new hirings, and so on. These are unsettling to
2622 | everyone, but perhaps a little less unsettling to the programmer whose
2623 | personal self-esteem is founded in capacity rather than in position.
2624 | Organizational chaos is a great opportunity for programmers to exercise their
2625 | magic power. I've saved this for last because it is a deep tribal secret. If
2626 | you are not a programmer, please stop reading now.
2627 | 
2628 | > Engineers have the power to create and sustain.
2629 | 
2630 | Non-engineers can order people around but, in a typical software company, can
2631 | create and sustain nothing without engineers, just as engineers typically
2632 | cannot sell a product or manage a business effectively. This power is proof
2633 | against almost all of the problems associated with temporary organizational
2634 | mayhem. When you have it you should ignore the chaos completely and carry on
2635 | as if nothing is happening. You may, of course, get fired, but if that happens
2636 | you can probably get a new job because of the magic power. More commonly, some
2637 | stressed-out person who does not have the magic power will come into your cube
2638 | and tell you to do something stupid. If you are really sure that it is stupid,
2639 | it is best to smile and nod until they go away and then carry on doing what
2640 | you know is best for the company.
2641 | 
2642 | If you are a leader, tell your people to do the same thing and tell them to
2643 | ignore what anybody else tells them. This course of action is the best for you
2644 | personally, and is the best for your company or project.
2645 | 
2646 | ## Glossary
2647 | 
2648 | This is a glossary of terms as used in this essay. These do not necessarily
2649 | have a standardized meaning to other people. Eric S. Raymond has compiled a
2650 | massive and informative glossary[HackerDict] that rather surprisingly can
2651 | pleasurably be read cover-to-cover once you can appreciate a fraction of it.
2652 | 
2653 | unk-unk
2654 | 
2655 |     
2656 | 
2657 | Slang for unknown-unknown. Problems that cannot presently even be
2658 | conceptualized that will steal time away from the project and wreck the
2659 | schedule.
2660 | 
2661 | boss
2662 | 
2663 |     
2664 | 
2665 | The person or entity that gives you tasks. In some cases this may be the
2666 | public at large.
2667 | 
2668 | printlining
2669 | 
2670 |     
2671 | 
2672 | The insertion of statements into a program on a strictly temporary basis that
2673 | output information about the execution of the program for the purpose of
2674 | debugging.
2675 | 
2676 | logging
2677 | 
2678 |     
2679 | 
2680 | The practice of writing a program so that it can produce a configurable output
2681 | log describing its execution.
2682 | 
2683 | divide and conquer
2684 | 
2685 |     
2686 | 
2687 | A technique of top-down design and, importantly, of debugging that is the
2688 | subdivision of a problem or a mystery into progressively smaller problems or
2689 | mysteries.
2690 | 
2691 | vapor
2692 | 
2693 |     
2694 | 
2695 | Illusionary and often deceptive promises of software that is not yet for sale
2696 | and, as often as not, will never materialize into anything solid.
2697 | 
2698 | boss
2699 | 
2700 |     
2701 | 
2702 | The person who sets your tasks. In some cases, the user is the boss.
2703 | 
2704 | tribe
2705 | 
2706 |     
2707 | 
2708 | The people with whom you share loyalty to a common goal.
2709 | 
2710 | low-hanging fruit
2711 | 
2712 |     
2713 | 
2714 | Big improvements that cost little.
2715 | 
2716 | Entrepreneur
2717 | 
2718 |     
2719 | 
2720 | The initiator of projects.
2721 | 
2722 | garbage
2723 | 
2724 |     
2725 | 
2726 | Objects that are no longer needed that hold memory.
2727 | 
2728 | busines
2729 | 
2730 |     
2731 | 
2732 | A group of people organized for making money.
2733 | 
2734 | company
2735 | 
2736 |     
2737 | 
2738 | A group of people organized for making money.
2739 | 
2740 | tribe
2741 | 
2742 |     
2743 | 
2744 | A group of people you share cultural affinity and loyalty with.
2745 | 
2746 | scroll blindness
2747 | 
2748 |     
2749 | 
2750 | The effect of being unable to find information you need because it is buried
2751 | in too much other, less interesting information.
2752 | 
2753 | wall-clock
2754 | 
2755 |     
2756 | 
2757 | Actually time as measured by a clock on a wall, as opposed to CPU time.
2758 | 
2759 | bottleneck
2760 | 
2761 |     
2762 | 
2763 | The most important limitation in the performance of a system. A constriction
2764 | that limits performance.
2765 | 
2766 | master
2767 | 
2768 |     
2769 | 
2770 | A unique piece of information from which all cached copies are derived that
2771 | serves as the official definition of that data.
2772 | 
2773 | heap allocated
2774 | 
2775 |     
2776 | 
2777 | Memory can be said to be heap allocated whenever the mechanism for freeing it
2778 | is complicated.
2779 | 
2780 | garbage
2781 | 
2782 |     
2783 | 
2784 | Allocated memory that no longer has any useful meaning.
2785 | 
2786 | garbage collector
2787 | 
2788 |     
2789 | 
2790 | A system for recycling garbage.
2791 | 
2792 | memory leak
2793 | 
2794 |     
2795 | 
2796 | The unwanted collection of references to objects that prevents garbage
2797 | collection (or a bug in the garbage collector or memory management system!)
2798 | that causes the program to gradually increase its memory demands over time.
2799 | 
2800 | Extreme Programming
2801 | 
2802 |     
2803 | 
2804 | A style of programming emphasizing communication with the customer and
2805 | automated testing.
2806 | 
2807 | hitting the wall
2808 | 
2809 |     
2810 | 
2811 | To run out of a specific resource causing performance to degrade sharply
2812 | rather than gradually.
2813 | 
2814 | speculative programming
2815 | 
2816 |     
2817 | 
2818 | Producing a feature before it is really known if that feature will be useful.
2819 | 
2820 | information hiding
2821 | 
2822 |     
2823 | 
2824 | A design principle that seeks to keep things independent and decoupled by
2825 | using interfaces that expose as little information as possible.
2826 | 
2827 | object-oriented programming
2828 | 
2829 |     
2830 | 
2831 | An programming style emphasizing the the management of state inside objects.
2832 | 
2833 | communication languages
2834 | 
2835 |     
2836 | 
2837 | A language designed primarily for standardization rather than execution.
2838 | 
2839 | boxes and arrows
2840 | 
2841 |     
2842 | 
2843 | A loose, informal style of making diagrams consiting of boxes and arrows drawn
2844 | between those boxes to show the relationships. This contrast with formal
2845 | diagram methodologies, such as UML.
2846 | 
2847 | lingua franca
2848 | 
2849 |     
2850 | 
2851 | A language so popular as to be a de facto standard for its field, as French
2852 | was for international diplomacy at one time.
2853 | 
2854 | buy vs. build
2855 | 
2856 |     
2857 | 
2858 | An adjective describing a choice between spending money for software or
2859 | writing it your self.
2860 | 
2861 | mere work
2862 | 
2863 |     
2864 | 
2865 | Work that requires little creativity and entails little risk. Mere work can be
2866 | estimated easily.
2867 | 
2868 | programming notation
2869 | 
2870 |     
2871 | 
2872 | A synonym for programming language that emphasizes the mathematical nature of
2873 | programming language and their relative simplicity compared to natural
2874 | languages.
2875 | 
2876 | strawman
2877 | 
2878 |     
2879 | 
2880 | A document meant to be the starting point of a technical discussion. A
2881 | strawman may lead to a stickman, tinman, woodman, ironman, etc.
2882 | 
2883 | wite-paper
2884 | 
2885 |     
2886 | 
2887 | An informative document that is often meant to explain or sell a product or
2888 | idea to an audience different than the programmers of that product or idea.
2889 | 
2890 | **Table of Contents**
2891 | 
2892 | Bibliography/Websiteography
2893 | 
2894 | ## Bibliography/Websiteography
2895 | 
2896 | ### Books
2897 | 
2898 | [Rules00] Guy Kawasaki, Michelle Moreno, and Gary Kawasaki. 2000.
2899 | HarperBusiness. _Rules for Revolutionaries: The Capitalist Manifesto for
2900 | Creating and Marketing New Products and Services_.
2901 | 
2902 | [RDev96] Steve McConnell. 1996. Microsoft Press.  Redmond, Wash. _Rapid
2903 | Development: Taming Wild Software Schedules_.
2904 | 
2905 | [CodeC93] Steve McConnell. 1993. Microsoft Press.  Redmond, Wash. _Code
2906 | Complete_.
2907 | 
2908 | [XP99] Kent Beck. 1999. 0201616416. Addison-Wesley. _Extreme Programming
2909 | Explained: Embrace Change_.
2910 | 
2911 | [PlanXP00] Kent Beck and Martin Fowler. 2000. 0201710919. Addison-Wesley.
2912 | _Planning Extreme Programming_.
2913 | 
2914 | [Prag99] Andrew Hunt, David Thomas, and Ward Cunningham. 1999. 020161622X.
2915 | Addison-Wesley. _The Pragmatic Programmer: From Journeyman to Master_.
2916 | 
2917 | [Stronger] Friedrich Nietzsche. 1889. _Twilight of the Idols, "Maxims and
2918 | Arrows", section 8._.
2919 | 
2920 | ### Web Sites
2921 | 
2922 | [PGSite] Paul Graham. 2002. _Articles on his website:
2923 | http://www.paulgraham.com/articles.html. All of them, but especially "Beating
2924 | the Averages"_.
2925 | 
2926 | [Hacker] Eric S. Raymond. 2003. _How to Become a Hacker_.
2927 | http://www.catb.org/~esr/faqs/hacker-howto.html.
2928 | 
2929 | [HackDict] Eric S. Raymond. 2003. _The New Hacker Dictionary_.
2930 | http://catb.org/esr/jargon/jargon.html.
2931 | 
2932 | [ExpCS] Edsger W. Dijkstra. 1986. _How Experimental is Computing Science?_.
2933 | http://www.cs.utexas.edu/users/EWD/ewd09xx/EWD988a.PDF.
2934 | 
2935 | [Knife] Edsger W. Dijkstra. 1984. _On a Cultural Gap_.
2936 | http://www.cs.utexas.edu/users/EWD/ewd09xx/EWD913.PDF .
2937 | 
2938 | ## Appendix B. History (As Of February, 2003)
2939 | 
2940 | ### Request for Feedback or Extension
2941 | 
2942 | Please send me any comments you may have on this essay. I consider all
2943 | suggestions, many of which have already improved this essay.
2944 | 
2945 | I have placed this essay under the GNU Free Documentation License. This
2946 | license is not specifically designed for essays. Essays are usually intended
2947 | to be coherent and convincing arguments that are writtien from a single point
2948 | of view in a single voice. I hope this essay is a short and pleasant read.
2949 | 
2950 | I also hope that it is instructive. Although not a textbook, it is broken into
2951 | many small sections to which new sections can be freely added. If so inclined,
2952 | you are encouraged to expand upon this essay as you see fit, subject to the
2953 | provisions of the License.
2954 | 
2955 | It may be arrogance to imagine that this document is worthy of extension; but
2956 | hope springs eternal. I would be joyous if it were extended in the following
2957 | ways:
2958 | 
2959 |   * The addition of a comprehensive reading list to each section, 
2960 | 
2961 |   * The addition of more and better sections, 
2962 | 
2963 |   * Translation into other languages, even if only on a subsection-by-subsection basis, and/or 
2964 | 
2965 |   * Criticism or commentary in-lined into the text. 
2966 | 
2967 |   * The ability to build into different formats, such as palm formats and better HTML. 
2968 | 
2969 | If you inform me of your work, I will consider it and may include it in
2970 | subsequent versions that I produce, subject to the provisions of the License.
2971 | You may of course produce your own versions of this document without my
2972 | knowledge, as explained in the License.
2973 | 
2974 | Thank you.
2975 | 
2976 | Robert L. Read
2977 | 
2978 | ### Original Version
2979 | 
2980 | The original version of this document was begun by Robert L. Read in the year
2981 | 2000 and first published electronically at Samizdat
2982 | Press(http://Samizdat.mines.edu) in 2002. It is dedicated to the programmers
2983 | of Hire.com.
2984 | 
2985 | After this article was mentioned on Slashdot in 2003, about 75 people sent me
2986 | email with suggestions and errata. I appreciate them all. There was a lot of
2987 | duplication, but the following people either made major suggestions or were
2988 | the first to find a bug that I fixed: Morgan McGuire, David Mason, Tom
2989 | Moertel, Ninja Programmer (145252) at Slashdot, Ben Vierck, Rob Hafernik, Mark
2990 | Howe, Pieter Pareit, Brian Grayson, Zed A. Shaw, Steve Benz, Maksim Ioffe,
2991 | Andrew Wu, David Jeschke, and Tom Corcoran.
2992 | 
2993 | Finally I would like to thank Christina Vallery, whose editing and
2994 | proofreading greatly improved the second draft, and Wayne Allen, who
2995 | encouraged me to initiate this.
2996 | 
2997 | ### Original Author's Bio
2998 | 
2999 | Robert L. Read lives in Austin, Texas, with his wife and two children. He is
3000 | currently a Principal Engineer at Hire.com, where he has worked for four
3001 | years. Prior to that he founded 4R Technology, which made a scanner-based
3002 | image analysis quality control tool for the paper industry.
3003 | 
3004 | Rob received a PhD from the University of Texas at Austin in 1995 in Computer
3005 | Science related to database theory. In 1987 he received a BA in Computer
3006 | Science from Rice University. He has been a paid programmer since the age of
3007 | 16.
3008 | 
3009 | ## Appendix C. GNU Free Documentation License
3010 | 
3011 | ### _Version 1.2, November 2002_
3012 | 
3013 | **Table of Contents**
3014 | 
3015 | PREAMBLE
3016 | 
3017 | APPLICABILITY AND DEFINITIONS
3018 | 
3019 | VERBATIM COPYING
3020 | 
3021 | COPYING IN QUANTITY
3022 | 
3023 | MODIFICATIONS
3024 | 
3025 | COMBINING DOCUMENTS
3026 | 
3027 | COLLECTIONS OF DOCUMENTS
3028 | 
3029 | AGGREGATION WITH INDEPENDENT WORKS
3030 | 
3031 | TRANSLATION
3032 | 
3033 | TERMINATION
3034 | 
3035 | FUTURE REVISIONS OF THIS LICENSE
3036 | 
3037 | ADDENDUM: How to use this License for your documents
3038 | 
3039 | > Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. 59 Temple Place,
3040 | Suite 330, Boston, MA 02111-1307 USA Everyone is permitted to copy and
3041 | distribute verbatim copies of this license document, but changing it is not
3042 | allowed.
3043 | 
3044 | ## PREAMBLE
3045 | 
3046 | The purpose of this License is to make a manual, textbook, or other functional
3047 | and useful document "free" in the sense of freedom: to assure everyone the
3048 | effective freedom to copy and redistribute it, with or without modifying it,
3049 | either commercially or noncommercially. Secondarily, this License preserves
3050 | for the author and publisher a way to get credit for their work, while not
3051 | being considered responsible for modifications made by others.
3052 | 
3053 | This License is a kind of "copyleft", which means that derivative works of the
3054 | document must themselves be free in the same sense. It complements the GNU
3055 | General Public License, which is a copyleft license designed for free
3056 | software.
3057 | 
3058 | We have designed this License in order to use it for manuals for free
3059 | software, because free software needs free documentation: a free program
3060 | should come with manuals providing the same freedoms that the software does.
3061 | But this License is not limited to software manuals; it can be used for any
3062 | textual work, regardless of subject matter or whether it is published as a
3063 | printed book. We recommend this License principally for works whose purpose is
3064 | instruction or reference.
3065 | 
3066 | ## APPLICABILITY AND DEFINITIONS
3067 | 
3068 | This License applies to any manual or other work, in any medium, that contains
3069 | a notice placed by the copyright holder saying it can be distributed under the
3070 | terms of this License. Such a notice grants a world-wide, royalty-free
3071 | license, unlimited in duration, to use that work under the conditions stated
3072 | herein. The "Document", below, refers to any such manual or work. Any member
3073 | of the public is a licensee, and is addressed as "you". You accept the license
3074 | if you copy, modify or distribute the work in a way requiring permission under
3075 | copyright law.
3076 | 
3077 | A "Modified Version" of the Document means any work containing the Document or
3078 | a portion of it, either copied verbatim, or with modifications and/or
3079 | translated into another language.
3080 | 
3081 | A "Secondary Section" is a named appendix or a front-matter section of the
3082 | Document that deals exclusively with the relationship of the publishers or
3083 | authors of the Document to the Document's overall subject (or to related
3084 | matters) and contains nothing that could fall directly within that overall
3085 | subject. (Thus, if the Document is in part a textbook of mathematics, a
3086 | Secondary Section may not explain any mathematics.) The relationship could be
3087 | a matter of historical connection with the subject or with related matters, or
3088 | of legal, commercial, philosophical, ethical or political position regarding
3089 | them.
3090 | 
3091 | The "Invariant Sections" are certain Secondary Sections whose titles are
3092 | designated, as being those of Invariant Sections, in the notice that says that
3093 | the Document is released under this License. If a section does not fit the
3094 | above definition of Secondary then it is not allowed to be designated as
3095 | Invariant. The Document may contain zero Invariant Sections. If the Document
3096 | does not identify any Invariant Sections then there are none.
3097 | 
3098 | The "Cover Texts" are certain short passages of text that are listed, as
3099 | Front-Cover Texts or Back-Cover Texts, in the notice that says that the
3100 | Document is released under this License. A Front-Cover Text may be at most 5
3101 | words, and a Back-Cover Text may be at most 25 words.
3102 | 
3103 | A "Transparent" copy of the Document means a machine-readable copy,
3104 | represented in a format whose specification is available to the general
3105 | public, that is suitable for revising the document straightforwardly with
3106 | generic text editors or (for images composed of pixels) generic paint programs
3107 | or (for drawings) some widely available drawing editor, and that is suitable
3108 | for input to text formatters or for automatic translation to a variety of
3109 | formats suitable for input to text formatters. A copy made in an otherwise
3110 | Transparent file format whose markup, or absence of markup, has been arranged
3111 | to thwart or discourage subsequent modification by readers is not Transparent.
3112 | An image format is not Transparent if used for any substantial amount of text.
3113 | A copy that is not "Transparent" is called "Opaque".
3114 | 
3115 | Examples of suitable formats for Transparent copies include plain ASCII
3116 | without markup, Texinfo input format, LaTeX input format, SGML or XML using a
3117 | publicly available DTD, and standard-conforming simple HTML, PostScript or PDF
3118 | designed for human modification. Examples of transparent image formats include
3119 | PNG, XCF and JPG. Opaque formats include proprietary formats that can be read
3120 | and edited only by proprietary word processors, SGML or XML for which the DTD
3121 | and/or processing tools are not generally available, and the machine-generated
3122 | HTML, PostScript or PDF produced by some word processors for output purposes
3123 | only.
3124 | 
3125 | The "Title Page" means, for a printed book, the title page itself, plus such
3126 | following pages as are needed to hold, legibly, the material this License
3127 | requires to appear in the title page. For works in formats which do not have
3128 | any title page as such, "Title Page" means the text near the most prominent
3129 | appearance of the work's title, preceding the beginning of the body of the
3130 | text.
3131 | 
3132 | A section "Entitled XYZ" means a named subunit of the Document whose title
3133 | either is precisely XYZ or contains XYZ in parentheses following text that
3134 | translates XYZ in another language. (Here XYZ stands for a specific section
3135 | name mentioned below, such as "Acknowledgements", "Dedications",
3136 | "Endorsements", or "History".) To "Preserve the Title" of such a section when
3137 | you modify the Document means that it remains a section "Entitled XYZ"
3138 | according to this definition.
3139 | 
3140 | The Document may include Warranty Disclaimers next to the notice which states
3141 | that this License applies to the Document. These Warranty Disclaimers are
3142 | considered to be included by reference in this License, but only as regards
3143 | disclaiming warranties: any other implication that these Warranty Disclaimers
3144 | may have is void and has no effect on the meaning of this License.
3145 | 
3146 | ## VERBATIM COPYING
3147 | 
3148 | You may copy and distribute the Document in any medium, either commercially or
3149 | noncommercially, provided that this License, the copyright notices, and the
3150 | license notice saying this License applies to the Document are reproduced in
3151 | all copies, and that you add no other conditions whatsoever to those of this
3152 | License. You may not use technical measures to obstruct or control the reading
3153 | or further copying of the copies you make or distribute. However, you may
3154 | accept compensation in exchange for copies. If you distribute a large enough
3155 | number of copies you must also follow the conditions in section 3.
3156 | 
3157 | You may also lend copies, under the same conditions stated above, and you may
3158 | publicly display copies.
3159 | 
3160 | ## COPYING IN QUANTITY
3161 | 
3162 | If you publish printed copies (or copies in media that commonly have printed
3163 | covers) of the Document, numbering more than 100, and the Document's license
3164 | notice requires Cover Texts, you must enclose the copies in covers that carry,
3165 | clearly and legibly, all these Cover Texts: Front-Cover Texts on the front
3166 | cover, and Back-Cover Texts on the back cover. Both covers must also clearly
3167 | and legibly identify you as the publisher of these copies. The front cover
3168 | must present the full title with all words of the title equally prominent and
3169 | visible. You may add other material on the covers in addition. Copying with
3170 | changes limited to the covers, as long as they preserve the title of the
3171 | Document and satisfy these conditions, can be treated as verbatim copying in
3172 | other respects.
3173 | 
3174 | If the required texts for either cover are too voluminous to fit legibly, you
3175 | should put the first ones listed (as many as fit reasonably) on the actual
3176 | cover, and continue the rest onto adjacent pages.
3177 | 
3178 | If you publish or distribute Opaque copies of the Document numbering more than
3179 | 100, you must either include a machine-readable Transparent copy along with
3180 | each Opaque copy, or state in or with each Opaque copy a computer-network
3181 | location from which the general network-using public has access to download
3182 | using public-standard network protocols a complete Transparent copy of the
3183 | Document, free of added material. If you use the latter option, you must take
3184 | reasonably prudent steps, when you begin distribution of Opaque copies in
3185 | quantity, to ensure that this Transparent copy will remain thus accessible at
3186 | the stated location until at least one year after the last time you distribute
3187 | an Opaque copy (directly or through your agents or retailers) of that edition
3188 | to the public.
3189 | 
3190 | It is requested, but not required, that you contact the authors of the
3191 | Document well before redistributing any large number of copies, to give them a
3192 | chance to provide you with an updated version of the Document.
3193 | 
3194 | ## MODIFICATIONS
3195 | 
3196 | You may copy and distribute a Modified Version of the Document under the
3197 | conditions of sections 2 and 3 above, provided that you release the Modified
3198 | Version under precisely this License, with the Modified Version filling the
3199 | role of the Document, thus licensing distribution and modification of the
3200 | Modified Version to whoever possesses a copy of it. In addition, you must do
3201 | these things in the Modified Version:
3202 | 
3203 |   1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission. 
3204 |   2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement. 
3205 |   3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
3206 |   4. Preserve all the copyright notices of the Document. 
3207 |   5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices. 
3208 |   6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below. 
3209 |   7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
3210 |   8. Include an unaltered copy of this License. 
3211 |   9. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence. 
3212 |   10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission. 
3213 |   11. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein. 
3214 |   12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles. 
3215 |   13. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version. 
3216 |   14. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section. 
3217 |   15. Preserve any Warranty Disclaimers. 
3218 | 
3219 | If the Modified Version includes new front-matter sections or appendices that
3220 | qualify as Secondary Sections and contain no material copied from the
3221 | Document, you may at your option designate some or all of these sections as
3222 | invariant. To do this, add their titles to the list of Invariant Sections in
3223 | the Modified Version's license notice. These titles must be distinct from any
3224 | other section titles.
3225 | 
3226 | You may add a section Entitled "Endorsements", provided it contains nothing
3227 | but endorsements of your Modified Version by various parties--for example,
3228 | statements of peer review or that the text has been approved by an
3229 | organization as the authoritative definition of a standard.
3230 | 
3231 | You may add a passage of up to five words as a Front-Cover Text, and a passage
3232 | of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts
3233 | in the Modified Version. Only one passage of Front-Cover Text and one of Back-
3234 | Cover Text may be added by (or through arrangements made by) any one entity.
3235 | If the Document already includes a cover text for the same cover, previously
3236 | added by you or by arrangement made by the same entity you are acting on
3237 | behalf of, you may not add another; but you may replace the old one, on
3238 | explicit permission from the previous publisher that added the old one.
3239 | 
3240 | The author(s) and publisher(s) of the Document do not by this License give
3241 | permission to use their names for publicity for or to assert or imply
3242 | endorsement of any Modified Version.
3243 | 
3244 | ## COMBINING DOCUMENTS
3245 | 
3246 | You may combine the Document with other documents released under this License,
3247 | under the terms defined in section 4 above for modified versions, provided
3248 | that you include in the combination all of the Invariant Sections of all of
3249 | the original documents, unmodified, and list them all as Invariant Sections of
3250 | your combined work in its license notice, and that you preserve all their
3251 | Warranty Disclaimers.
3252 | 
3253 | The combined work need only contain one copy of this License, and multiple
3254 | identical Invariant Sections may be replaced with a single copy. If there are
3255 | multiple Invariant Sections with the same name but different contents, make
3256 | the title of each such section unique by adding at the end of it, in
3257 | parentheses, the name of the original author or publisher of that section if
3258 | known, or else a unique number. Make the same adjustment to the section titles
3259 | in the list of Invariant Sections in the license notice of the combined work.
3260 | 
3261 | In the combination, you must combine any sections Entitled "History" in the
3262 | various original documents, forming one section Entitled "History"; likewise
3263 | combine any sections Entitled "Acknowledgements", and any sections Entitled
3264 | "Dedications". You must delete all sections Entitled "Endorsements".
3265 | 
3266 | ## COLLECTIONS OF DOCUMENTS
3267 | 
3268 | You may make a collection consisting of the Document and other documents
3269 | released under this License, and replace the individual copies of this License
3270 | in the various documents with a single copy that is included in the
3271 | collection, provided that you follow the rules of this License for verbatim
3272 | copying of each of the documents in all other respects.
3273 | 
3274 | You may extract a single document from such a collection, and distribute it
3275 | individually under this License, provided you insert a copy of this License
3276 | into the extracted document, and follow this License in all other respects
3277 | regarding verbatim copying of that document.
3278 | 
3279 | ## AGGREGATION WITH INDEPENDENT WORKS
3280 | 
3281 | A compilation of the Document or its derivatives with other separate and
3282 | independent documents or works, in or on a volume of a storage or distribution
3283 | medium, is called an "aggregate" if the copyright resulting from the
3284 | compilation is not used to limit the legal rights of the compilation's users
3285 | beyond what the individual works permit. When the Document is included in an
3286 | aggregate, this License does not apply to the other works in the aggregate
3287 | which are not themselves derivative works of the Document.
3288 | 
3289 | If the Cover Text requirement of section 3 is applicable to these copies of
3290 | the Document, then if the Document is less than one half of the entire
3291 | aggregate, the Document's Cover Texts may be placed on covers that bracket the
3292 | Document within the aggregate, or the electronic equivalent of covers if the
3293 | Document is in electronic form. Otherwise they must appear on printed covers
3294 | that bracket the whole aggregate.
3295 | 
3296 | ## TRANSLATION
3297 | 
3298 | Translation is considered a kind of modification, so you may distribute
3299 | translations of the Document under the terms of section 4. Replacing Invariant
3300 | Sections with translations requires special permission from their copyright
3301 | holders, but you may include translations of some or all Invariant Sections in
3302 | addition to the original versions of these Invariant Sections. You may include
3303 | a translation of this License, and all the license notices in the Document,
3304 | and any Warranty Disclaimers, provided that you also include the original
3305 | English version of this License and the original versions of those notices and
3306 | disclaimers. In case of a disagreement between the translation and the
3307 | original version of this License or a notice or disclaimer, the original
3308 | version will prevail.
3309 | 
3310 | If a section in the Document is Entitled "Acknowledgements", "Dedications", or
3311 | "History", the requirement (section 4) to Preserve its Title (section 1) will
3312 | typically require changing the actual title.
3313 | 
3314 | ## TERMINATION
3315 | 
3316 | You may not copy, modify, sublicense, or distribute the Document except as
3317 | expressly provided for under this License. Any other attempt to copy, modify,
3318 | sublicense or distribute the Document is void, and will automatically
3319 | terminate your rights under this License. However, parties who have received
3320 | copies, or rights, from you under this License will not have their licenses
3321 | terminated so long as such parties remain in full compliance.
3322 | 
3323 | ## FUTURE REVISIONS OF THIS LICENSE
3324 | 
3325 | The Free Software Foundation may publish new, revised versions of the GNU Free
3326 | Documentation License from time to time. Such new versions will be similar in
3327 | spirit to the present version, but may differ in detail to address new
3328 | problems or concerns. See http://www.gnu.org/copyleft/.
3329 | 
3330 | Each version of the License is given a distinguishing version number. If the
3331 | Document specifies that a particular numbered version of this License "or any
3332 | later version" applies to it, you have the option of following the terms and
3333 | conditions either of that specified version or of any later version that has
3334 | been published (not as a draft) by the Free Software Foundation. If the
3335 | Document does not specify a version number of this License, you may choose any
3336 | version ever published (not as a draft) by the Free Software Foundation.
3337 | 
3338 | ## ADDENDUM: How to use this License for your documents
3339 | 
3340 | To use this License in a document you have written, include a copy of the
3341 | License in the document and put the following copyright and license notices
3342 | just after the title page:
3343 | 
3344 | > Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute
3345 | and/or modify this document under the terms of the GNU Free Documentation
3346 | License, Version 1.2 or any later version published by the Free Software
3347 | Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-
3348 | Cover Texts. A copy of the license is included in the section entitled "GNU
3349 | Free Documentation License".
3350 | 
3351 | If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
3352 | replace the "with...Texts." line with this:
3353 | 
3354 | > with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover
3355 | Texts being LIST, and with the Back-Cover Texts being LIST.
3356 | 
3357 | If you have Invariant Sections without Cover Texts, or some other combination
3358 | of the three, merge those two alternatives to suit the situation.
3359 | 
3360 | If your document contains nontrivial examples of program code, we recommend
3361 | releasing these examples in parallel under your choice of free software
3362 | license, such as the GNU General Public License, to permit their use in free
3363 | software.
3364 | 
3365 | ## Colophon
3366 | 
3367 | This work is licensed under the GNU Free Documentation License. It was
3368 | originally written in LaTeX, then ported to DocBook. It is available in
3369 | transparent copy in the DocBook/XML format. A build system and special
3370 | instructions on processing are part of the transparent copy package, though
3371 | building from the source is system dependent. The source can be built into
3372 | either HTML or PDF format, and extension to other formats should be possible
3373 | and is encouraged.
3374 | 
3375 | The original version of this document was written by Robert L. Read without
3376 | renumeration and dedicated to the programmers of Hire.com.
3377 | 
3378 | 
3379 | 


--------------------------------------------------------------------------------