Originally found here
By TheophileEscargot Fri Jan 28th, 2005 at 11:53:03 AM EST Software A brief guide to software development in the real world. Aimed mainly at new developers: experienced programmers already know most of this. This guide is for hands-on programmers, not managers.BREAK
Introduction Most textbooks and methodology guides start with statistics proving that software projects are disastrously prone to failure. I'll take that for granted. They then propose complicated rules designed for a fantasy business world where cooperative workers idealistically work towards the common goal of maximizing shareholder value. A couple of weeks in a typical office should disabuse you of that. Real world companies are made up of individuals working for their own goals: career advancement, more money, or just the chance to slack off. Occasionally it may be in someone's interest to build a successful project. Usually it's more useful to sabotage it. This leads to the real reason for the perpetual software crisis: 1. Most software fails because it is designed to fail Why you should want your project to succeed A developer rarely benefits from the failure of his project. There are exceptions, such improving your resumé by choosing bleeding-edge technology that may also cripple the project. However, few developers escape the consequences: they may be stuck maintaining an inadequate system long after the project manager has moved on to better things. In addition, since management is a less specialized skill, it is easier for a manager to change jobs than it is for a developer. Sabotage There are two kinds of sabotage: deliberate and incidental. The direct manager of a project has an incentive to see the project succeed. As we will see later, he may also have incentives to make the project fail, but generally he wants to get it working, at least in the short term until he gets promoted. In most companies, promotion is competitive. This means that the direct manager's competitors have an incentive to make him fail: deliberate sabotage. This tendency is most prevalent in non-software houses that have several teams of in-house developers. It obviously doesn't arise if there is only one software development manager, and in software houses the chance of expansion renders the competition less fierce. Because everyone has to pay lip service to the good of the company, deliberate sabotage has to be disguised as incidental sabotage. Nevertheless, be aware that it's a good idea to keep sensitive information, such as estimates and necessary purchases away from potential rivals. Beware of casual conversations with the enemy. 2. Loose lips sink projects Incidental sabotage is more widespread. Anyone who has input into the project will be working for their own ends. Examples: the legal department want to make things safe for them by insisting on huge legal disclaimers at the expense of usability. Designers want to maintain an impressive portfolio by using flash displays at the expense of bandwidth and small footprints. Analysis Some early software methodologies advocated a 40-20-40 model: spend the first 40% of time on analysis and design, 20% of the time building the system, 40% of the time on testing. Modern methodologies tend to focus on incremental development: build a prototype and continuously improve. Neither of these are acceptable to the business commissioning the project. Accounting want to know the cost of the project when planning the fiscal year. HR want to know how many people to hire or fire. No-one is going to authorise 40% of a project's likely budget to find out what it will cost to build. No-one is going to sell the idea of building a system first then finding out exactly what it will do later. Therefore, you will continue to develop the traditional way: take a guess based on inadequate analysis and pray that you've padded it with enough contingency. The project will probably overrun, but see incidental sabotage: that's not the accountants' problem. 3. Don't trust the analysis Descoping As the system is being built, the consequences of the poor analysis will show up: requirements will become more complicated than you thought. Fortunately, due to incidental sabotage, much of the functionality will be unnecessary. At some point, you will need to descope: reduce the functionality so you can finish the system. There are two aspects to doing this successfully: 4a. Descope early As soon as possible in the project, try to work out which features will be cancelled. For every requirement, get some explanation of why it's there. From this you can often identify the important bits: build those first, and structure the system so the others can be added if necessary. 4b. Admit descoping late While you should actually descope as early as possible, you should admit you've descoped as late as possible. First, the person who identifies a problem is usually blamed for that problem: kill the bearer of bad news is the principle. Second, admit it too early and people have the chance to add more pointless requirements: it's safer to wait until there's panic in the air. Only propose descoping when the project is already behind schedule. Also remember that someone who points out a problem early is a troublemaker; someone who fixes a problem at the last minute is a hero. Architecture It can be useful to make your architecture reflect organizational lines. If one team is likely to be unreliable, try to make them responsible for an isolated module of the system. If possible, make the rest of the system work independently of it. In any case, make sure a failure there cannot be blamed on something else. Be aware that architecture charts can give management incorrect ideas about where the workload lies. Consider this diagram: +----------+ +-----------+ +-----------+ +------------+ +----------+ | GUI | | Docs | | I/O | | Data | | Utils | | | | | | | | | | | | Alice | | Alice | | Alice | | Bob | | Alice | +----------+ +-----------+ +-----------+ +------------+ +----------+ On showing this breakdown to any given manager, it will be clear that Alice has taken on the vast bulk of the project work, while Bob is basically slacking. Bob cannot explain to the manager that designing data structures for this project is the most difficult component, and the rest is trivial. Additionally, any undue progress made by Bob on the data structure can be sabotaged by Alice at any time by changes to project modules under her control 5. Make sure architecture assigns blame clearly Managing Management The manager of a project usually wants it to succeed, but not necessarily in the same way as the developers. The project manager only needs it to work in the short term: he doesn't care if it's easy to maintain. However, an unmaintainable project can be a trap for a developer, who might spend years making tiny changes. There are also circumstances where the project manager benefits from doing things the wrong way. A manager gains status from the size of his team: it may be advantageous to enlarge the project. It can help to keep an eye on any magazine subscriptions held by the manager. Try to disparage technologies you don't want to work with, encourage useful technologies. The goal of meetings, as far as the manager is concerned, is to appear in control and abreast of the project. Your goal is to make sure that they think they are in control and abreast of the project, while keeping all details from them. Most managers will happily collude in this, since they have no desire to know what is happening, so long as they are seen to be so aware and are rigorously kept blissfully ignorant of their own ignorance. Remember that managers are essentially secretaries who can fire you. 6. Managers don't want to know the truth: keep it from them. Documentation Documentation is an essential tool in the twin goals of ass-covering and of managing management. It also provides dangerous traps for potential enemies. The political trick is to strike the correct tone of opaque vagueness and unshakeable authority. The true use of documentation is to bridge the inevitable gap between what the project is supposed to do and what it actually does. Politically written documentation bridges this gap by appearing to claim the former without actually denying the latter. On close examination, it will be found to say nothing at all. This is the true origin of the fallacy that code is its own best documentation: The code itself is the only document which may be relied upon in any way in order to find out how the software might actually behave under this or that set of circumstances. However, anyone actually saying so only reveals themselves as a troublemaker. There is also a three-way conflict between the interested parties: 1. The people specifying the documentation want it to be as detailed as possible, in as much volume as possible. The more documentation, the better, as this increases their importance. 2. The people writing the documentation want it as effortless as possible 3. The people eventually using the documentation want it as accurate as possible. The usual compromise between 1 and 2 is to create vast amounts of inaccurate, out-of-date documentation. Since it's never updated, it's usually useless to 3. The best way to sneak useful documentation past the system is to create a brief "Overview" document, small enough to be kept up-to-date. This will at least give maintenance programmers an idea of what the system is supposed to do. 7. Keep documentation brief enough to be kept up-to-date If possible, try to get accurate documentation created: otherwise you will find yourself doing endless maintenance and support on a system that only you understand. Ass-covering Document everything. Preserve your old emails. If possible, keep them in a personal archive so that you can use them, but they cannot be used against you. Especially if you're busy, keep a record of what you've done every day: either in your official timesheets or in private notes. Especially when under pressure it can be tempting to leave them to later: but this leaves you dangerously vulnerable when the blamestorming begins. When asked incredulously "how on earth did it take you so long to do this", you need to be able to say first: "Because I had to do X, Y and Z and then undo them", and point to your record as evidence. When asked "why on earth did you do that?" you need to be able to say "because you told me to in this email sent on this date." In turn, the emails you sent will be used in evidence against you. Keep a professional tone: before sending any sensitive email take a moment to think how it would look at an industrial tribunal. The chief difficulty is reaching a satisfactory compromise between ass-covering and not appearing too negative. If you know something is going to fail, make sure you point it out and have a record, but try to present it in a positive way. Say that it is a "major risk", rather than a certain failure. Try to request additional resources or time even when you know they will be denied. 8. Preserve records privately Error messages and logfiles As well as being later than you expect, the system will be less reliable than you expect. Make sure your debug and logfiles give you plenty of information. As with architecture, make sure that your error messages assign blame appropriately. Overtime As the deadlines whoosh past, the pressure will grow to do unpaid overtime. Reduced concentration and the unavailability of other people mean that generally an hour of overtime achieves much less than an hour of normal time, so it's not very effective. The thing to remember is that your line manager wants you to do overtime because he's being pressured by his managers. In many cases he doesn't want you to do overtime, since he knows that the extra bugs aren't worth it, but to be seen to be doing overtime. The key rule is: 9. Overtime only counts when people see it It's usually better to do overtime in the evening than the morning, if there are more people around to see it. Weekend overtime is usually pointless since there are rarely witnesses. Remember that you're not just being visible to your boss, but the office as a whole. Your overtime is useless to him unless it's visible to his boss, or else other people who contribute to your team's reputation. Keep to the minimum possible. Remember that the earliest part is most valuable since there are more witnesses: better to do half an hour Monday to Thursday than two hours on Wednesday. It also sounds better to say: "I've worked late four nights this week." No-one will be keeping track that closely anyway. Finally, remember that with deadlines pressing, the last thing your line manager wants is to fire you. Threats are likely to be empty in the short term, and quickly forgotten when the project is over. As part of his empire, you are contributing to his status: he doesn't want to get rid of you even if you're useless. You're only likely to be fired if the company as a whole is reducing numbers, and in that case no amount of work guarantees safety. This article was created as a collaboration on ko4ting the K5 wiki by clover kicker, motty, R Mutt, Scrymarch and TheophileEscargot.