Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share

migrated from stackoverflow.com Sep 6 '11 at 15:39

This question came from our site for professional and enthusiast programmers.

locked by Yannis Rizos Mar 12 '12 at 20:34

This question exists because it has historical significance, but it is not considered a good, on-topic question for this site, so please do not use it as evidence that you can ask similar questions here. This question and its answers are frozen and cannot be changed. More info: help center.

show 1 more comment

50 Answers

up vote 162 down vote accepted

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.

share
1  
@quickly_now - Read them a long time ago during college. Not a bad read. I agree, you can explain it - you can explain it in any language when the person you're explaining to already understands the "abstraction" behind it (code, mathematic equation and meaning of it...) // If he doesn't - you will have trouble explaining it in any language. –  Rook Sep 7 '11 at 18:59
4  
@Rook - good point. Explaining quantum mechanics to a primitive tribe whose vocabulary is limited to which direction the Elk moved in would be kinda hard. –  quickly_now Sep 7 '11 at 23:16
show 2 more comments

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.

share
15  
Which is why I specified, "A non-programming manager should not need more than that." –  Malfist Sep 6 '11 at 20:16
35  
@Loren Pechtel: I'd like to site there and watch this guy actually read pages of "Create an integer variable named X. Set it to 0. Create an integer variable named Y. Set it to 0. Create an integer variable named Z. Set it to 0. Create an integer variable named X position. Set it to 0. Create an integer variable named Y position. Set it to 0. Create an integer variable named Z position. Set it to 0. Create an integer variable named X rotation. Set it to 0. Create an integer variable named Y rotation. Set it to 0. Create an integer variable named Z rotation. Set it to 0."... –  FrustratedWithFormsDesigner Sep 6 '11 at 21:24
9  
@Frustated It's a lot easier with syntax highlighting! "[p32767, l21, c8] Increase pX by the size of an Integer. Increase Sum by the value pointed to by pX. Increase i by 1. If i is less than 3, go to page 32768, line 17, column 42. Otherwise, go to page 32767, line 21, column 8." –  muntoo Sep 6 '11 at 23:33
9  
@muntoo, you need to inline all those functions so you don't have to jump back and forth between pages. Otherwise one might have a lot of trouble getting back up the stack. –  Kibbee Sep 7 '11 at 1:08
15  
@Frustrated: So whose voice are you imagining? I can't decide between Sean Connery and Morgan Freeman. –  Beta Sep 7 '11 at 1:57
show 8 more comments

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?

share
21  
+1 for diagnosing micromanagement. In my own words: get the f___ out of there! –  tdammers Sep 6 '11 at 18:35
5  
A manager that needs to understand every line of the code is called a programmer. –  James Poulson Sep 7 '11 at 14:46
show 1 more comment

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?

share
57  
Make sure after you have spent two hours explaining ten lines that he understands that there are 50,000 (or whatever) lines of code left to be explained. –  HLGEM Sep 6 '11 at 17:43
6  
Actually a very sane way to follow up. Make him see the ignorance of his ways. –  Kibbee Sep 7 '11 at 1:13
4  
@reinierpost: your method is pure genius. –  heltonbiker Sep 7 '11 at 1:31
5  
If you're going to do this, first tell the boss why it's a bad idea in general and THEN demonstrate. If you don't, this may appear like you are pulling a "trick" on him and put him on the defensive. –  nerdytenor Sep 7 '11 at 16:31
5  
Never tell people their ideas are bad!! You can discuss, though, what it would take to make them come true, and perhaps even give some ideas for taking shortcuts. If this leads them to conclude that the idea wasn't viable, or makes the initial idea morph into something completely different, and they should happen to notice this at some point, they'll shrug and say: that's life. –  reinierpost Sep 8 '11 at 12:28
show 2 more comments

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.

share
13  
Even with an English translation, a non-programmer may very well believe: /* and this line is transferring deposits to the correct account */ deposits.TransferAll(acctInfo); –  IAbstract Sep 6 '11 at 15:45
15  
If the boss is "afraid you are going to make your code do something he doesn't approve or is aware of" this will do nothing to alleviate his fears. The same person is providing the translation who wrote the code. What's to stop them from lying about what it does? There's something else going on here. –  mmc Sep 6 '11 at 21:47
4  
COBOL was meant to be read in English. –  oosterwal Sep 6 '11 at 22:51
1  
Perhaps he is trying to figure out what the code does to see if he agrees with the reasoning and perhaps get better ideas. In any case, it is not his job to do so, at least not that way... –  heltonbiker Sep 7 '11 at 1:26
add comment

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).

share
1  
Exactly as well as you might expect. ;) However, the point had been made, and the requests stopped. I don't know whether that was because I had convinced her to the validity of my argument or she decided it wasn't worth the hassle and gave up. –  John N Sep 8 '11 at 7:21
show 1 more comment

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
share
show 2 more comments

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.

share
3  
I think english should be the language. The boss should ask for all the software to be written in a DSL (domain specific language), then he can make changes to the way the system works. –  David d C e Freitas Sep 7 '11 at 13:34
show 1 more comment

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.

share
7  
we need to be careful about characterizing anyone as "an idiot". While it is personally satisfying for us as programmers to do this, I don't think it is professional, and any request from any manager, no matter how strange, should be treated based on its merits. –  funkymushroom Sep 6 '11 at 18:53
6  
@funkymushroom: The merits of this request are that he's an idiot. –  DeadMG Sep 6 '11 at 21:04
3  
@funkymushroom - I think we can be allowed a little levity on this site. Afterall, you go by funkymushroom. –  JeffO Sep 6 '11 at 22:25
2  
@Jeff: Point well taken. I am by no means a stick-in-the-mud. There are, however, two kinds of "idiot". The "Malicious Idiot" and the "Ignorant Idiot" and I have worked with both. The first should be ignored, he is dangerous to our careers, and the second can be a good ally, so we should teach him. –  funkymushroom Sep 7 '11 at 14:09
show 1 more comment

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. :)

share
3  
I disagree with Mikey's comment. Blindly following orders is foolish. Asking 'why?' at each request has saved me countless hours of unnecessary work and saved my company plenty of money in the process. It's called consultation, and those who don't fear their bosses do it liberally and to great effect. When people who work for me suggest something, I also ask them 'why?' as well. In both cases, it's seeking justification, and it's perfectly acceptable to do so. –  Soviut Sep 8 '11 at 9:34
show 1 more comment

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).

share
show 3 more comments

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.

share
add comment

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 :-)

share
3  
I think this is the best answer here. I don't understand all the reluctance to giving it a try, I mean you will be getting paid to sit there and explain your code! Hell, unless your code is utter crap you will probably enjoy it, and no matter how good it is you'll probably find some bugs and places for improvement. –  Bill K Sep 7 '11 at 15:13
1  
I had a teacher that explained stuff while typing out code displayed through a projector. Maybe this could be done a bit like a driving lesson. If you can't through all the code at least you can give a better sense of what's being done and how. –  James Poulson Sep 7 '11 at 19:54
1  
I'm trying to get into the teaching business myself, and I gave a similar answer. I'm with @Bill, I'm seriously disappointed that people would take such a reclusive stance. Are we screwed up for believing that it's worth spending time explaining even just a small part of the code? –  Rei Miyasaka Sep 8 '11 at 12:44
1  
@Rei: Attitudes, bad or good, tend to take over large subsets of otherwise similar people. I've had a breadth of experience (engineer, grad student, professor, consultant, long-term employee) so I like to think that gives a perspective. Also, my attitudes have shifted over the years. –  Mike Dunlavey Sep 8 '11 at 16:37
add comment

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."

enter image description here

share
show 1 more comment

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.

share
18  
Actually, it tells me a lot about this person... –  Marjan Venema Sep 6 '11 at 17:17
5  
That's what "doesn't say much about" means in this context -- it says a lot, indeed, but it just doesn't indicate much good about the individual. –  Joseph Weissman Sep 6 '11 at 18:10
add comment

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.

share
show 1 more comment

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.

share
add comment

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.

share
add comment

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!

share
1  
A cost-benefit analysis should do the job. Maybe the manager has some additional benefits to bring in. If it doesn't pay off it's hard to enforce and defend to the upper management. –  mbx Sep 7 '11 at 9:26
add comment

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.

share
show 2 more comments

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.

share
show 2 more comments

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.

share
add comment

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.

share
3  
Documenting line-by-line != selling the project. There should already be a document which provides this information, it's called requirements. I agree about your 2 jobs description, but documenting to that level is not going to be beneficial to selling the project/system/application. There is an appropriate level of documentation for presenting your work, and this is not it. –  cdkMoose Sep 6 '11 at 17:58
show 2 more comments

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.

share
show 1 more comment

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.

share
add comment

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.

share
show 1 more comment

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.

share
add comment

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... ;-)

share
add comment

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.

share
add comment

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

share
2  
Are you referring to the manager or the programmer? –  Nathan Long Sep 6 '11 at 20:48
show 1 more comment

Not the answer you're looking for? Browse other questions tagged or ask your own question.