Should you write good documentation and clean code to increase the "Bus Factor"?

Question

One of the main goals of software development companies is to increase their Bus factor This is also advocated in a talk that was organized by Google.

That means that you should code and document everything in a way that if you're run over by bus tomorrow, the project can still continue. In other words, you should make yourself easily replaceable by another programmer with a similar skill set to yours.

Being replacable, isn't that against the interest of a developer? In the book, 48 laws of power Rule 11 states that you should try to keep people dependent on you, in order to gain power, which then translates into monetary rewards.

Apart from the scenario, where you need some documentation for yourself in order to continue a project after 6 months of pause, there seems to be a clear conflict of interest here between the developer and the software company.

So as a programmer, should you really write excellent documentation and easily readable code for everyone; or should you write code and documentation in a way that it does the job and you yourself can understand it, but another person may have trouble understanding it?

Answer 1

You should strive to become irreplaceable not by writing code noone else understands, but by gathering more experience and knowledge than others. The former way makes you a developer everyone tries to avoid working with, as they will fear and loath maintaining code you wrote. The latter way you become a sought out team member, whom managers want to have in their team.

In my experience writing clean, well documented (and preferably self-documenting) code has always paid off. In fact I took almost every opportunity to help and teach others (as well as learning from them when they knew something better), and I hardly ever felt in danger of getting replaced by someone less capable than me. In fact, this usually helped the whole team work better and solve problems faster, which is every manager's dream - and a sensible manager doesn't want to replace members of a good team.

Answer 2

If you are irreplaceable, you can't be promoted.

Answer 3

If you are going to manipulate organizations or people so transparently they'd better be stupid or in a jam that leaves them no other choice. A well run software development shop would look at your obscure code and missing documentation and simply fire you before you could do much damage. If they're poorly run, or unable to get any other developers to work for them, why would you want to have a sinecure with them?

PS Neither Mr. Greene nor Machiavelli actually accomplished much aside from writing books that tried to flatter would-be "hard men" of the time. Take their advice with a grain of salt.

Answer 4

You do not want to be irreplaceable. You do not want to make people feel depending on you, you want them to appreciate you. Generally, you want to stay far away from people, who believe even half of the laws of power should be applied to relationships (professional or personal).
These rules are an instruction set on how to successfully establish a win-lose situation. What you want, is a win-win situation.
As soon as people start feeling, you're trying to push them on the losing side of a win-lose situation, they will fight back. Attempts to establish win-lose situations often end up in a lose-lose outcome, because you're effectively wasting resources on getting your partner into a losing position, instead of investing them into the overall success of your partnership.

If you do this with your employers, they will try to force measures on you, to reduce your knowledge monopoly. Mostly, these will be ridiculous guidelines on how you must do your work and will thereby turn your work life into a living hell. Also, they will call you at 3 o'clock in the night when something breaks, because you're the only person, who can fix it. Trying to exploit such situations as leverage is likely to backfire and cause you more trouble.

The graveyards are full of indispensable men.
- Gaulle, Charles De

So cut the crap and do your work properly. If not for anything else, then for you, because you're likely to be the poor soul, who has to make some changes to the code 2 years from now.

Answer 5

The negative responses aren't too surprising, given the number of better-than-average programmers this site attracts. Talented people don't generally need to resort to these kinds of security-through-obfuscation tactics. But I worked at a Fortune 500 automotive supplier with a few not-so-talented developers who had carved out little fiefdoms for themselves, which they zealously guarded by creating copious amounts of documentation for the horrendous interfaces they had designed.

One guy's whole job was maintaining the code for a module that bridged two entirely separate subsystems, allowing modules on each system to communicate via a UART. Basically, it was Serial Programming 101. Instead of just creating a general interface that looked something like this:

  int sendData(int targetModule, void *data, size_t byteCount);
  int recvData(int sourceModule, void *data, size_t maxBytes);

he created separate opcodes for every single message that any two communicating modules might want to send to eachother. Which meant his module needed to know about every message, and needed to be updated whenever a message was added or changed. Talk about inappropriate intimacy!

The thing is, this guy kept a Word doc neatly listing all the opcodes/messages, and diligently updated it as necessary. It became his whole job. A few times a week, he'd send out a new revision to all the people unfortunate enough to have him on their critical path. And this was seen as 'professional', since management loved seeing documentation. Kinda makes me weep for the automotive industry.

I guess my point is: sometimes writing documentation can, in fact, protect mediocre programmers. Managers often can't tell the difference between a good design and a bad one, and many are forced to make technical decisions with limited information. It's incredibly stressful for them. Seeing a Word doc with dozens of neatly formatted tables can be very comforting—even if what it describes is a fundamentally bad idea.

Answer 6

Being replacable, isn't that against the interest of a developer?

I hate to break it to you, but everyone is replaceable. Sure, sometimes it may be a slight challenge to replace you (if you're experienced and bright enough), but it's light years from impossible.

The way to truly be a valuable commodity to your employer (not just current employer, but any employer) is to demonstrate the ability to write code that easy to grok by anyone reading the code (little ramp up time to work with it) and document the code (anyone can get a high level overview of your systems without digging into code).

Actually being good at code documentation is a tough quality to come by these days, so that alone will help set you apart from others.

Clean and well documented code is also worthy of being put on a resume (at least, tangible outcomes of it, i.e. "we were able to bring n new developers on with minimal ramp up and assistance due to my documentation), where being sneaky about making yourself "irreplaceable" isn't.

Answer 7

Being replacable, isn't that against the interest of a developer?

Depends what the interests of that developer are. If you are one who wants to stick it out in a single job for your entire career, be completely indispensable to a company that rewards incompetence and make good money then yes, absolutely.

But what happens when the company crashes, probably because they hired too many people like that? Where are you going to go next? What when they ask you why you stayed in the same job for 15 years? And so on.

Now look at it a different way: How many developers have lost their jobs by being someone who writes code that anyone can read?

The only likelihood of that happening is if the company is in trouble and making people redundant. If that is happening, you're better off getting out, and you'll be very well prepared for the upcoming interviews. Plus your conscience will be completely free -- you won't be leaving behind inexplicable code which you wrote for your own self-gain.

I don't know what kind of person you are, but that serves my interests better.

Personally, I think one of my greatest strengths is in automating my own job. What do you think a company tends to think when I've become surplus to my own requirements? Do they think "ok, we'll get rid of him now" or do they think "why don't we move him into another role and let him do it again"?

Answer 8

Being replacable, isn't that against the interest of a developer?

You are right, but I think you misunderstood the meaning of replaceable. I could find a 1000 developers that write hectic code, undocumented that can quickly turns into an unmaintainable mess.

A developers that produce not only steady programs, but also clean code, informative documentation and ensures the continuity of the project, that's not only irreplaceable, that's priceless.

Answer 9

I'll address this question from a different perspective, since there are already several excellent answers.

Consider what happens when you play petty games by trying to make yourself "irreplaceable" though preventing other people from learning how your code works. You stay in the same job maintaining your very own messes for as long as the company tolerates you. And that's the best case scenario, the worst case scenario is that other, more talented and more ethical engineers and managers in your company see the hindrance your poor practices imposes on the company and they decide to do something about it: by firing you and rewriting everything from scratch. It's been done. In fact, it's a fairly common thing to happen.

Now consider what happens when you write good code and good documentation. You create a component or a system that works well, that after a while in operation working out the bugs works smoothly and hardly needs to be looked at. It takes little effort to maintain it. You can then move on to bigger and better projects, with a solid victory under your belt. People will recognize you for having done good work and will start to respect your opinion. You'll have the ability to move up in the foodchain and make more meaningful decisions, or do more important and impactfull work, or manage projects at a higher level. Your career will improve, you'll get promoted, you'll make more money, you'll gain recognition and approval by your peers, you'll add more and more successes of more and more important projects to your track record.

Which route would you prefer?

Answer 10

If you're the single point of failure, your client (or employer) will probably try to replace you; there's always a point where it's less costly to replace software than maintain it, no matter how essential it seems. There is a reason IT is one of the most outsourceable professions.

On the other hand, being replaceable gives you several priceless benefits:

• being able to take vacation
• not being on call
• freedom to leave and work on a new and exiting project

Answer 11

If you don't spend 5 minutes writing up some quick documentation then you're going to spend an hour re-reading and explaining it to people when they need to use your code.

Even worse could be spending days searching for a new job because your boss found out you weren't writing maintainable code.

Answer 12

Excellent documentation will eventually be obsolete with refactoring/evolutions, and keeping it up to date is really time consuming.

Clean code + unit test > excellent documentation

Answer 13

The answer to your question is "yes". Yes you should write good documentation and clean code. Deliberately doing otherwise displays a lack of integrity, which, while increasingly prevalent in the business world isn't somehow suddenly a "good" thing.

No one is irreplaceable. People who manufacture a situation whereby they think they are tend to find out the hard way that they are not. Manufacturing a co-dependency for yourself is counterproductive as it also limits you, not just your employer.

Answer 14

One of the main goals of software development companies is to increase their Bus factor

False premise. The main goals of a software development company (every one that I've worked at, anyway) are to produce the best software they can and to make money, not necessarily in that order. Reducing the "bus factor" is just one way to avoid losing money.

Law 11 Learn to keep people dependent on you.

What does that mean to you?

Do you want people to depend on you because you've undermined them in such a way that they can only move forward with your help? Or do you want people to depend on you because you're smart and insightful, reliable, trustworthy, and able to help others do their jobs better too? Do you want to make your colleagues look bad without your help, or do you want them to appreciate you for making them look good?

It's your call.

Answer 15

(assuming production code)

I tend to go a bit further. I've written about making programs "idiot proof", but I don't always qualify that: I write a lot of code that other people will not see or work with (at least, that is the expectation when it is written). I am the idiot I am trying to defend myself from in that case. It's a good thing when your program detects problems for you, and the problem has been simplified so much that it's quite obvious that there is an error, and its origin. The truth is, implementation details are obvious when you write a program (unless you are implementing it prematurely), but they should be abstracted and error resistant for clients (even when module locality exists). The reason is that programs become very complex. Sometimes you can separate problems, but not all the time. If you keep your components very strict, simple, well encapsulated, and idiot proof, they do tend to scale well and most defects are detected before they are shipped. It's easier to reuse, and you have more confidence and an easier time reusing the programs, As well, those complex programs that you write only become more complex (even to you) after some time away from the program. When you read it in 6 months, it can take an absurd amount of time to understand and debug compared to the idiot proof version. If a component introduces a breaking change, it can go undetected for a long time otherwise. Programs are complex; you can't escape that reality, but you can make it idiot proof, which will make your life a lot easier when something goes wrong or when it must be reused or altered. Therefore, the idiot proof approach means that your software can be understood, reused, or maintained by your juniors or people newer on the team as well (not just somebody as good/experienced as you). Replacement is a separate concern: If people love working with your programs, you're doing a good job -- don't worry about replacement. Sure, I could come up with scenarios where unintelligible programs could save your job, but writing a good program others can use and maintain is clearly the lesser evil (look at the others' resopnses). If I catch myself writing something that is not idiot proof, I try to fix that.

Apart from the scenario, where you need some documentation for yourself in order to continue a project after 6 months of pause, there seems to be a clear conflict of interest here between the developer and the software company.

You really have no idea what you were thinking some of the time when you revisit dormant implementations. When you are really experienced, then the problem is simpler because you can rely more on established methodologies or approaches which you use. That, however, also assumes these methodologies are invariant. Even though the documentation may lax, you still have to be defensive in your implementations (e.g. you know better than to pass NULL in this scenario -- test that condition).

So as a programmer, should you really write excellent documentation and easily readable code for everyone; or should you write code and documentation in a way that it does the job and you yourself can understand it, but another person may have trouble understanding it?

I recommend the idiot proof approach, which is even clearer and more error resistant than the bus factor approach. Write your programs and documentation such that it is easily understood by somebody external to the project -- it's good for you too. Doing so will increase your value to your company and team, they will not want to replace you.

Answer 16

You've fundamentally misunderstood the game. The game is not to keep doing the same old things that you've done before, being responsible for all the code you've written because no one else gets it. The game is to complete a project and move onto the next one, leaving behind code that someone else can easily understand and work with in your absence so that you can do new things and take on more and different responsibilities. Your premise only works if you're happy to be stuck doing the same thing over and over with no chance to learn or improve.

Answer 17

I'm also going to point out that if you don't have occasion to look at that code very often, you too will have trouble figuring it out in six months if you obfuscate it deliberately.

Answer 18

I document what little code I write, not so that others can read it, but so that I can read it in 3 months time! It's about making maintenance easier. If you are responsible for code you wrote, and you can't fix bugs that show up later down the line, then you'll want it to be well documented... It's pretty irrelevant how replaceable you are if you aren't able to do your job!

Answer 19

Every "irreplaceable" computer professional I've had the misfortune of interacting with was replaced, in large part because they were trying to hold their employers' resources hostage. When I've had people who report to me tell me their time is to valuable to "waste" documenting, I replace them as soon as possible.

It would seem that if a prospective employee considers the 48 laws of power to be ethically or morally acceptable, then you would be better off without them.

Answer 20

If you REALLY want to be irreplaceable (which you might want to reconsider after reading all the answers...) - why stop with not documenting the code?

There's a truly brilliant guide about how to write unmaintainable code you should definitely read: http://thc.org/root/phun/unmaintain.html

Enjoy! (I most certainly did...)