My boss wants a narrated line-by-line English explanation of our code

Question

I have been specifically asked to give line by line (or as appropriate - for example, image by image, etc.) explanation or commentary which my boss wants to be able to read and follow.

Since he is not a programmer, he can not follow the code so wants it all translated into English.

Has anyone been asked to do this before?

I have commented on all of the source code and used JSDoc to generate full documentation of all functions, variables, etc... and included an implementation example, and full working demos with comments throughout.

Is there anything else I can do to comment the code for non-programmers?

This isn't a reasonable request, is it?

---

UPDATE

In the end, I managed to explain why it was not a good use of time to do what he was asking. He is a reasonable guy, and just did not have an understanding of what my job involves. Once he saw this post, I think he quickly understood that it was not a normal request.

I did provide documentation that is suitable for another programmer to follow (JSDoc and inline comments - as well as some extra notes on technical issues), and a very broad flow chart diagram of the main logic of the program for my boss to follow.

In the end, all parties were satisfied and we have moved on.

Answer 1

No, it is not a reasonable request!

TALK HIM OUT OF IT, or have someone else talk him out of it, by all means. That is an irrational idea, which although doable is so expensive to do it should never actually be done. An overview of functions and subroutines is reasonable, but to "explain" every code line is not. It would be more effective for him to learn to read the language in hand, than to do that.

The next thing he will be asking for is to translate mathematical formulas, or whatnot into English text. Although certainly possible that introduces much room for error and misinterpretation, and should never be done. Just like "translating" code to English.

Answer 2

Do you have design documents? Those are the English explanation of what the code does. A non-programming manager should not need more than that.

Answer 3

Is there a micro-manager of the year award? It sounds like your boss deserves a nomination. Someone who believes he needs line-by-line level understanding of the code, but doesn't want to learn how to read it directly, is about as perfect as micro-manager as can be imagined.

One advantage of being a developer is that the difficulty of understanding code prevents micromanagement beyond a certain degree, at least at the detailed implementation level, at least by non-technical management, because even the most hard-core micro-manager recognizes that they are over their head at that level. But your boss's genius may found a way to shatter the silicon curtain.

And, as a bonus, it wastes tremendous amounts of developer time doing the translation, even before he uses the English translation to start suggesting various improvements (I'm assuming he knows how to code better than the programmers, even though he can't read the code, and will be able to share his wisdom just as soon as someone translates it, otherwise why would he need every line translated?).

So, no, it's not a reasonable request, and I've never heard of it before. And I feel for you. I think everyone may need to start quietly looking for another job, because once he starts using code translation as a management tool it's probably going to be a brutal place to work (er, a more brutal place to work).

On the plus side, maybe you can get a new anti-pattern named after your situation? How about the "Dirty Hungarian Phrasebook" anti-pattern, after the Monty Python skit where a tobacconist is trying to communicate with someone who doesn't speak English by using a Hungarian phrase book that has comically false translations?

Answer 4

Sit down with him and talk him through 10 lines of the code. Explain every detail until you both agree he understands it to the extent he wanted to.

Maybe this experience is all he's looking for: just an impression of what your work looks like to you, and what the software looks like from your point of view. That's a good thing in my book.

If after this, he still wants you to continue, say: notice how many questions I had to ask; imagine if I would have had to explain all of this without being able to ask questions, how could I possibly have known what to include and what to leave out? How much time would it have taken before the results would be useful to you? Now how many lines do you want me to do in this way?

Answer 5

I don't think it's a reasonable request. SOURCE CODE is not meant to be read in English (or any other language for that matter).

Maybe he's afraid you are going to make your code do something he doesn't approve or is aware of. If that's the case, I don't think there is something you can do about it. You will have to write the documentation or maybe convince him/her to hire someone to audit your code.

Answer 6

It really is very simple:

• You have been hired because of your skills as a programmer
• Your manager does not have these skills
• Ergo, your manager should not reasonably expect to be able to fully understand what you do

I've had a similar experience to this in a previous job. My manager was an accountant (and thus highly low-level detail oriented), and did not understand or truly trust programming. She could not comprehend that she, as a non-technical person, should not expect to be able to grasp the minutia of what I wrote. After many requests for excessive documentation and requests to train non-technical users in how to manage and alter the code (yes, really), I stopped trying to fob her off, and outright refused. The analogy I used to explain was simple:

• I am not an accountant
• I should not expect to understand every single transaction or posting in our accounts
• This does not mean that the accounts are wrong, or untrustworthy, simply because I don't understand them
• This is made possible by trusting the person who compiled them

At the end of it all, this is what this sounds like to me: a manager who has difficulty trusting their employees; or fears that they will leave, and thinks that this is an effective way to mitigate against it.

The only solution to this is to sit down and explain why this doesn't make sense. It is your job to understand the code and make it possible for someone with a similar skill set to yours to understand it, not your manager's. Showing them this thread may be a good idea (or a really, really terrible one, depending on their personality).

Answer 7

Line-by-line, is ridiculous. What I might suggest is offering to generate docs from comments and give him that. That was sufficient for a number of Canadian Government grants and audits that I've worked on in the past.

He won't get line-by-line but he'll get method-by-method which should still be more granularity than he needs.

Some existing solutions, depending on your platform:

• C# : sandcastle
• Java : javadoc
• "C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D." : doxygen

Answer 8

It would be much faster for him to learn to read code than it would be to translate the entire code of any interesting application to English. Besides, we tried that with COBOL and it didn't help at all. If he's not willing to learn, but just wants to make his ignorance someone else's problem, you have a seriously pointy-headed boss.

Answer 9

Use your technical expertise to pursuade your boss.

1. Let him know that it will take just as long to do this as it did for you to code it in the first place (Feel free to make it longer.).
2. Ask him how up-to-date this document needs to be. Inform him all coding changes will now take at least twice as long.
3. If you or anyone else finds any bugs, ask him if you should fix them now or wait until you are done psuedo coding. Remind him about #1 & #2.

Like all bad solution suggestions, it's better to identify the problem. Maybe your boss is getting hit with technical questions by upper-management and he feels embarassed since he's unable to answer. There could be one particular section of code that he feels the most concerned about, so you could limit this massive undertaking to just that area.

By submitting a sample, he may come to the conclusion that if you don't understand how coding works (What is a loop and what is it doing to all these items?) it doesn't mattere what language it is in. He's better off understanding the application from a power user perspective. I think it is fair for you to let him know that you'd rather be writing real code/hint - I'm looking for another job.

Answer 10

Why?

A line-by-line commentary not reasonable, but here's what I'd ask: why do you want this?

Is it because...

• you want a complete understanding of what the software does (not necessarily how)?
• you want to be sure another programmer can pick up the project if I leave?
• you want to see that I'm doing real work?

There may be a reasonable desire behind this request, and you may be able to make your boss happy by figuring that out and meeting that need.

Update

Based on Mikey's comment, perhaps I stated this a little too bluntly. I don't mean that you should literally say "why do you want this?", just that you should find that out. Wording and tone of voice make a big difference. Specifically, you could say something like:

"I've been thinking about your request to have an explanation of every single line of code. It's a little bit unusual to do things that way. I was wondering if maybe there's something I'm not communicating well to you about my work. What is it that you really want to understand about our code, or about what I'm doing? What are you trying to accomplish here?"

Of course, it's possible that your boss is totally unreasonable. But it's more likely that he doesn't know how outlandish this request is and has some rational goal in mind.

If not, start polishing your resume. :)

Answer 11

Sounds like a good chance to try literate programming. Google it. :)

But... it's not necessarily an entirely unreasonable request. Part of your job (the more important part, imo) is to communicate your algorithm(s) to other developers, and, if necessary, non-technical people. Solitary genius programmers who can't communicate are always problematic, I think.

To that end, your code should be darn clear (meaning: either truly self-documenting or well documented, and by "self-documenting" I mean variables and functions have one meaning or responsibility and their names reflect that clearly). Your boss may have good reasons for his request. Maybe (I'm just guessing here) you or your predecessor have a reputation for impenetrable, fragile code and this is your boss's remedy. It's a bit extreme, but might be a useful exercise for you. I assume he knows that it takes time to write better docs (and if he doesn't, he should be educated -- it's just like writing a term paper: takes longer to write than to read).

Answer 12

Even a line by line translation will not effectively convey the meaning of each line of code. A programmers understanding of a line of code is always in the context of many factors. Get into something like a piece of multi-threaded code and the english translation will not make any more sense than the raw code. Think about functionality that is spread between multiple functions/files. Some code makes absolutely no sense without explaining extensive amounts of other code. Try to explain the different parts involved in dependency injection "line by line" and you will see what I mean. Just about anything that goes beyond God-function procedural code will require an extensive amount of programming knowledge just to understand the English translation. Also, look at something as simple as an if/else decision statement. There is no line-by-line, since the next line is dependent on run time data. The next line could be one of several possibilities. By the time you have explained what your application does, you will have made your PM into a programmer and you will both be 5 years older.

Answer 13

Since I used to teach programming, I would be only too happy to give it a go.

He will quickly find out he's getting more than he bargained for, which will make me sad because I like explaining things :-)

Answer 14

When you refer to your 'Boss' is this "a middle manager in charge of you/your team"? or The Owner of your Company? Are you paid "by the hour" or "on a salary"?

IF your boss is a middle tier manager who is accountable, TALK TO HIS BOSS, point out that to meet your boss' requirement your productivity to the company will be cut to 1/3 of what it could be.

IF your boss is "the guy who signs the checks" explain to him the same thing, just more diplomatically. Your job has gone from "Write the code" to "Write the code, write the explanation of the code, explain the explanation."

Answer 15

A flow chart will probably be of more benefit to him. This is certainly an unusual request and doesn't say much about him as a manager.

Answer 16

The fact that your boss is willing to spent some time understanding the code that you written, you could use for your benefit. Try introduce him to Cucumber: http://cukes.info/

and make your boss write BDD test for you in the future.

Answer 17

He should not bother to know any of that. Tell him, that in software development implementation is subject to change. Event design is subject to change. Tell him about information hiding, encapsulation and abstraction.
He, as part of your team, as client of your code, in a broader sense, should only work with a clear, high level abstraction of what your code does. The same way any layer of your code works with another layer of somebody else's code. Knowing any more than that, will only slow him down, and risks him making assumptions based on the inner workings of your code. Those assumptions will cease holding, when you have to change your code, which becomes a problem, if he built any kind of system or process based on them.
And also having to do this kind of work will reduce your efficiency. Not only will you have to make subsequent changes in two different places, but it will also negatively impact your work morale, which will reduce your output even further.

Answer 18

The beauty of English is that is obfucates beautifully. If you use this to your advantage, you may never heve to deal with this sort of request again. I would take a small piece of the code as a sample but one which is very abstracted and not at all easy to understand. I would then write up the comments in technical english as if you were writing it up for a chapter in a programming book. The longer and more complicated to follow, the better. Tell him how many hours it took you to document this one feature. Then explain that it is only 1/10th of 1 % (use actual figures based on lines of code if you can, they are probably worse than this) of the actual code base. When he realizes he has no clue what the English translation says and that it will take 20,000 man-hours to do this level of documentation he will back off fairly quickly. But be very earnestly trying to accomplish his task. Don;t try this if you can't pull that off and he suspects you are playing him.

Answer 19

This looks like a candidate for a special holiday-issue pointy-haired-boss Dilbert strip! His request certainly does not sound reasonable at first glance.

Humor aside, try to find out what he really needs, and why, then advise him of what it will cost in dollars or hours to give him that, and let him decide if he wants to spend that much money on it.

As for yourself, count up the hours it will take you to meet his seemingly bizarre request and then determine if you wouldn't be better off investing a fraction of that amount of time in finding a new job working for an employer willing to treat you as a professional!

Answer 20

Bring him into your office and give him a tour of your code.

He'll realize part way through that he made an absurd demand, and he'll walk away and never bother you again.

If you don't give into his demands to help him try to understand your code, he'll find different but equally absurd ways to poke at you.

This is a case where appeasement works better than abrasion.

Answer 21

It would be very nice if we had a translator "Language X to English" that does this. Then one could grin and say, no problem, boss, you'll have that in a minute. And then comes a mail with some megabytes of text that reads:

• Let a be a new integer array with 20 elements.
• Let x be a variable to store integers.
• Set x to 0
• While x is smaller than 20 do what is prescribed in the next 2 lines
• set the array element of a with the index x to the result of calling nThPrime with the argument x+1
• increase x by 1
• ....

Another option would be to suggest programming in Shakespeare henceforth.

Answer 22

My boss wants a narrated line-by-line English explanation of our code

Tough.

Since he is not a programmer, he can not follow the code, so wants it all translated into English.

If he is not a programmer, he should not be reading the code. At all.

Provide high-level documentation instead.

This isn't a reasonable request, is it?

No.

Answer 23

As a programmer, you really have "two" jobs.

The first is to create good programs. The second is to "sell" them to customers inside and outside the company.

Your boss' request "hurts" your first job. It takes more time to document your programs. On the other hand, he's actually making you work harder on your "second" job.

Your boss is asking you to document your program in English for HIS benefit, and presumably for the benefit of people he has to deal with, inside and outside the company. If you help him to do his job, it should work to your benefit in the long run, when you ask him for more hardware, personnel, or money for raises. After all, he asked you to do more work.

Answer 24

I think BDD would suit well with this problem, although it seems that your project is near-completion, so kinda hard to implement it in now, so it's more like for future reference.

With BDD use-cases are described as humanly-readable documents that are then translated into automated functional tests.

Answer 25

Probably, this request is a good time to learn things like ANTLR. Take ANTLR, take your language's grammar, parse all the code you have, traverse your AST generating template-based descriptions for every node, so i++ is described as increase i by 1 using postfix increment operator. That should be really funny. Your boss may also want this tool to be included to the build script, so every time you make any changes, he'll receive a ~20 MB e-mail describing what the new version does.

P.S. Just kidding, he's an idiot.

Answer 26

Although I agree that this is an unreasonable request, your boss may appreciate something like the output of Docco, which separates your code and line-by-line or clause-by-clause comments into two-column HTML output, with the code on one side and prose on the other. You have to type the comments yourself, of course, but the presentation is rather nice IMHO, even for non-technical readers. See, for instance, a line-by-line commented section of the annotated code for Underscore.js. There are Python and shell script versions as well.

Answer 27

It's possible that your boss is just uninformed and intimidated, but is actually a reasonable person. If so, reasoning with him/her might work - a casual conversation where you promise to provide "what he really wants" ie; a prose guide to what the program is doing.

If it comes down to "my way or the highway" better check your gas now.

Answer 28

You could write some acceptance tests using a behaviour-driven-design framework such as cucumber? That won't explain the code; it will explain what it does, and in natural-language. It also has the benefit of being executable, so you can always be sure the documentation is up-to-date, because if it isn't, the test-runner will be red.

Check out the intro video. Perhaps it's a good diversion while you find a new boss... ;-)

Answer 29

Your manager is almost certainly distressed by the fact that he doesn't understand what the people do that he's managing, and he doesn't have the background to understand the results that they produce.

I doubt he thought this solution through very thoroughly, and it probably seemed sensible to him at first glance. But that's largely because he doesn't understand what programming code actually is.

Any programmer understands the absurdity of this request, but we do because we intuitively know that once you get past the language, all that's revealed is the algorithm, which is equally cryptic.

// Set s to the first address in the server list
server_info *s = cmd->servers;
// Loop until s is NULL
while (s) {
    // call the server's init function passing our current ID and address
    s->init(proc->id,*addr);
    // call log::info with our custom message
    log::info("Starting server %s",s->name);
    // Set s to the value returned by the server's next() function
    s=s->next();
} // end of loop

The problem here is that while the comments explain what each line does, you still have no idea what the code really does unless you understand what all the implications are. It's obvious if you're a programmer and have seen this pattern before; but show this to someone who only understands sales, and he will be just as confused after reading the comments as he was before.

You could actually save time by teaching your boss some basic programming. If he wants to read your code, give him the tools to be able to do so. Most languages are pretty compact syntax-wise, and learning the structure only takes an hour or two. He will, almost certainly, give up after a few days, but at least he'll know what he's passing on, and more importantly why he doesn't want to read your code.

Answer 30

IMHO...if he's responsible for getting the task done, he should know how it works... :)