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
show 1 more comment

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.

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

Ideally, every code should be readable and understandable to either your colleagues or your boss. If your boss wants this, your code isn't expressive enough, it doesn't communicate your intent well enough. Don't narrate your code, write your code so that it resemble an English narration as much as possible! See Domain Specific Languages (DSLs) for details.

Some links:

share
add comment

Yes, I agree that it's not a reasonable request for us, but maybe he is curious to know how it all works. So for a non-programmer, I would say use flowchart. So that your boss can see the big picture or you can also go into as much details as you want in flowcharts as per his requirements. There are many flowchart applications available. I found Balsamiq Mockups helpful. I hope that helps.

share
add comment

I would just show him the video Quick-sort with Hungarian (Küküllőmenti legényes) folk dance and then explain to him how long it would take to do this for all lines of code you have.

share
add comment

I create "in English" explanations for almost every other line of my code - in the code comments. I don't see this as an unreasonable burden. Certainly the way you describe it, it seems a bit fishy. Anything more than that is a red flag that you might have an unreasonable boss or there is a problem with your working relationship.

share
show 1 more comment

Making line by line explanation will definitely increase your coding file size, this is the reason for introducing documentation separately.

Anyway, if he wants much more very detailed line by line explanation, then just attach the documentation of the programming language in which you used to code and ask him to refer from that (for example, if you are coding in Java then refer to JavaTM 2 Platform, Standard Edition, v 1.4.2 API Specification ).
Definitely this will work. :-)

share
add comment

"Sure no problem"

Start at line one of your JavaScript application, <!DOCTYPE html>

And drill down all the way to the CPU electronics...

Do this for each byte of code.

Explain what doctype is, explain the prupose, explain the history, explain the alternatives.

Problem?

share
1  
This. I did my duty by reading through all the comments before posting myself, and here is what I planned to say at the very end. If you try to talk him out of it, he's going to think you have something to hide. Simply give him what he wants and demonstrate the absurdity of it. –  Mud Sep 10 '11 at 4:41
add comment

I would also point out to your boss that to do this would take X hours of your time. after he sees what this will take, I'd be suprised if he asks you to continue.

I'd also invite him/her into a code review of your feature. Not so he/she can understand anything, but just to understand that this is what you and your team do internally to NOT have to verbalize your code. If your boss is asking for this, my gut is telling me he/she doesn't trust your team or trust that they are taking due diligence. By letting him/her sit through a code review, it would demonstrate that due dilligence and he/she would hopefully leave you alone.

share
add comment

I would say that showing him this question and all the answers that you have got, would help him understand that he's being unreasonable! So try and ask him to see all the answers here, but of course in a non-offensive and respectful way. He'll understand the way developers work!

Additionally, I would say try and use diagrams, like a lot of people already mentioned. But again, do give serious thought to showing him the responses given here!

share
add comment

You first must establish the extent of the request. You have to make sure you’re not making the bossster-under-the-desk scarier than the monster actually is.

Is it more: //The method gets a customer. Or more: // Some long detailed programming explanation including what is an int, what does ‘void’ mean, and includes math rewritten into English concepts?

Likely it is somewhere in-between.

If it turns out that the request is too extreme:

I would suggest you explain to your boss that while it seems like a small thing, programmers are not trained to either thing or express themselves in this manner, apart from in the most general sense of code. There are people who are trained to convey complex ideas to laypeople, they’re called technical writers.

One issue I think have not been addressed well, or at all. In order to do this, it should be done as the code is written. Is he aware of how much time this will eat up when trying to meet deadlines?

Given these types of comments should not be in the code, there is no good way or tool (that I am aware of) to make this work.

This is a maintenance nightmare. Even if some method is found to pull this off when generating code, once the code enters maintenance how would the comments be maintained?

If after a chat, if you believe your boss still does not get it, start looking for new jobs. The person who only has a single bat-shit crazy idea is rarer than a unicorn.

And if this person is opening code files, I hope you have some really good source control in place.

share
add comment

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

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

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

We have all had managers at some point or another that want something ridiculous like this. It's hard to not go off half cocked, but it is important that you don't- he'll just dig in. Maybe you can make him a list of pros and cons and go through them with him. In my opinion, the first item in the con side is good code is self documenting. But they hardly ever fall for that.

share
add comment

Ask them Why or what their motivation for the request is, then honestly determine the costs involved and share them with the requester. If this is an unreasonable and possibly malicious request, then find another job.

share
add 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

I would just say you are more than will to do it but it will take you x weeks to complete and is he sure he wants / needs you to do it?

Surely he will realise you time would be better spent elsewhere?

share
add comment

You could also suggest a move to Literate Programming and COBOL or FORTRAN since http://stackoverflow.com/questions/152160/using-noweb-on-a-large-java-project or just ask why he doesn't require every graphist to explain every single use of any tool he makes.

You're a specialist, you are expected to deliver a high end product, not to explain in detail that you paint a greenish stroke here, and then apply a 2px gaussian blur etc.

share
add comment

A picture is worth a thousands words. Draw some Use Case and Sequence diagrams. They should be sufficient to explain the purpose/flow of the software.

P.S: Whatever you do avoid stuffing your source with comments. That will add bloat especially if it's stored in a versionning system. Add some numbers/codes instead which refer to the diagrams suggested.

share
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

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

Code IS English already, 'for', 'if', 'else', etc. Just do a search and replace for certain characters. For example, replace '>' with 'greater than'.

share
add comment

This isn't an irrational idea, and quite logical. It is her duty to check through the code and see if there is something there to break.

Now it is up to you, as what you can do your best to make it simple. As someone already suggested, making a good design document with simple UML diagrams can be the best way. It is not always necessary to comment line-by-line. As an end user, (or a customer) someone can make a request, now it is up to you, how you full-fill it (making design docs or end user docs or writing comments line by line).

Even in my job, when I joined a new company I was told to do so by my lead. When you are new at a place, you need some time to build your reputation, and at that time such requests come. I fulfilled it, by creating UML diagrams modulewise.

share
add 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

Um ...

Did you build your code from a specification? Was the requirement correctly documented?

If he's a half decent manager he should be asking "Does this meet the requirements?"

If you said yes to the above ... give him those docs + the stuff you already mentioned, if he still wants more he's an idiot and clearly should not be managing a dev team.

And before that dumbass comes back with "well what do we know" ... i'm betting there's at least 50 years of combined experience in this thread alone.

Role of a manager: 1. Identify and assign objectives. 2. Ensure they are correctly carried out. 3. Don't ask dumb questions that should already be answered.

Frankly if you have a solution already built he should know what's been written. If he has no idea what you're doing then I'm guessing smoeone above him has demanded details of what his team are up to.

You could be really smart and link back your solution to the business plan and show where you are meeting the core objectives of the business then pass on the details to his line manager stating that your own manager does not seem capable of understanding you.

You'll probably get his job.

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

Give him a flow chart lol ...

Either that or he's asking for user documentation?

share
add comment

It's a very unreasonable request. You're hired to write code and program, and any documentation you write is supposed to help other developers or programmers working on the same project - not your boss or employee.

share
add comment

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

First, ask what the goal here is. Come up with alternate ways to accomplish whatever explanation he has.

Next, provide an estimate of how long this would take, both in terms of how many hours it would take to put together and how long it would take to run through. Ask, in delicately phrased terms, if both your time isn't spent better doing something else instead.

Start by telling him how many thousands of lines of code your app is.

If that fails, as already suggested, provide a sample of what he should expect when you narrate the entire code with him. That should satisfy him.

If he persists, start looking around for a new job.

BTW, this is really a case where the project manager should intervene and explain to the boss that this level of detail is not in everyone's interest.

share
add 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

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