154

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.

Billy Moon
  • 329
  • 2
  • 5
  • 14
  • Locked for historical reasons, please see ["Lock the top-voted questions that are closed"](http://meta.programmers.stackexchange.com/questions/3298/lock-the-top-voted-questions-that-are-closed) for further details. – yannis Mar 12 '12 at 20:34

50 Answers50

159

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.

gnat
  • 21,442
  • 29
  • 112
  • 288
Rook
  • 19,861
  • 9
  • 53
  • 96
  • Interesting: Go read Richard Feynmans lectures on Physics. You will find that much of it is a carefully worded argument, in English (if X then Y must be true, and hence Z... etc). Little maths. The point I'm making is that you can explain things in English. Whether you SHOULD is another matter. – quickly_now Sep 07 '11 at 10:14
  • 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 07 '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 07 '11 at 23:16
  • I could get the 'intention' of your manager at times to micro-manage. But, if the code was very clear in itself, then he can just read it as a english text. – Arvind Chinniah Sep 13 '11 at 10:00
149

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.

Justicle
  • 101
  • 3
Malfist
  • 3,641
  • 5
  • 29
  • 40
  • Note that he said "line by line". That's more detail than you'll find in the design documents. – Loren Pechtel Sep 06 '11 at 20:05
  • 15
    Which is why I specified, "A non-programming manager should not need more than that." – Malfist Sep 06 '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 06 '11 at 21:24
  • 2
    @Frustrated: Heck, it may be worth it just for the entertainment factor... – Lightness Races in Orbit Sep 06 '11 at 22:53
  • 3
    @Frustrated: Hey, you could write a documentation generator! Either that, or program in COBOL, which is self-documenting. – Robert Harvey Sep 06 '11 at 23:32
  • 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.*" – Mateen Ulhaq Sep 06 '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 07 '11 at 01:08
  • 15
    @Frustrated: So whose voice are you imagining? I can't decide between Sean Connery and Morgan Freeman. – Beta Sep 07 '11 at 01:57
  • @muntoo: Love the line based `goto`:s. Sure takes me back. 8-D – Macke Sep 07 '11 at 10:32
  • 2
    Design documents describe what the program *should* do. Apparently the manager wants to check (in English) whether the program really *does* that. – Hans Kesting Sep 07 '11 at 12:58
  • 2
    @Hans Kesting: I'd like to see him try to keep the program state in his head as he manually steps through it. Also, overcommented code is *still* no guarantee that the code does what the *comments* say it should do (`if (x = true) launchMissiles();`, anyone? Not to mention code maintenance.). This just embeds the design document into the source, in the clumsiest way possible. – Piskvor left the building Sep 07 '11 at 13:46
  • @Piskvor Unfortunately, in VB, the missiles aren't guaranteed to launch. :( – Mateen Ulhaq Sep 08 '11 at 02:11
  • @muntoo: Language-specific constructs were not my point, I just picked one of the best-known easily-overlooked bugs. The point I was trying to make is that the **comments are still narrating what the code *should* do, not what it *actually* does** (they are comments, after all) - and for a person not literate in the given programming language (whichever it is), it will be difficult to verify or falsify the correlation between comments and code. – Piskvor left the building Sep 08 '11 at 06:58
112

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?

dgw
  • 103
  • 4
psr
  • 12,846
  • 5
  • 39
  • 67
91

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?

reinierpost
  • 587
  • 6
  • 8
  • 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 06 '11 at 17:43
  • 6
    Actually a very sane way to follow up. Make him see the ignorance of his ways. – Kibbee Sep 07 '11 at 01:13
  • 4
    @reinierpost: your method is pure genius. – heltonbiker Sep 07 '11 at 01: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 07 '11 at 16:31
  • @nerdytenor True. It could be dangerous – Adam Lynch Sep 07 '11 at 21:30
  • When a manager gives me an unreasonable request, I first try to argue the point, then give him what he wants. In this case, a single function or module would suffice to show him that he is asking for something he doesn't really want. – Andrew Neely Sep 08 '11 at 11:16
  • 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 08 '11 at 12:28
42

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.

Pablo Santa Cruz
  • 291
  • 2
  • 7
  • 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 06 '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 06 '11 at 21:47
  • 4
    COBOL was meant to be read in English. – oosterwal Sep 06 '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 07 '11 at 01:26
32

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

John N
  • 258
  • 5
  • 10
  • how did your manager take your explanation? – Jeff Martin Sep 07 '11 at 19:56
  • 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 08 '11 at 07:21
25

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
Steven Evers
  • 28,200
  • 10
  • 75
  • 159
16

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.

kevin cline
  • 33,608
  • 3
  • 71
  • 142
  • 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 07 '11 at 13:34
  • I think the mention of Cobol sums it up. Anyone who's printed out a simple hello world knows how ridiculously wordy this language is. It was a good move towards something intelligible but way too formal. – James P. Sep 07 '11 at 19:45
15

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.

JeffO
  • 36,816
  • 2
  • 57
  • 124
  • 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 06 '11 at 18:53
  • 6
    @funkymushroom: The merits of this request are that he's an idiot. – DeadMG Sep 06 '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 06 '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 07 '11 at 14:09
  • @funkymushroom - agree, so I took it out. – JeffO Sep 07 '11 at 17:33
12

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

Nathan Long
  • 3,667
  • 3
  • 24
  • 28
  • -1 for this answer: If you want to hold on to your job (or at least leave it voluntarily) you should not ask such a boss 'why'? This is something that must be finessed, as others have suggested. – Vector Sep 07 '11 at 03:14
  • 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 08 '11 at 09:34
10

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

JohnL4
  • 634
  • 4
  • 12
  • I've had a look at the Wikipedia page. It reminds me of the "structured " I saw during studies. You use human language to represent programming structure line by line with expressions like `if blah then add 1 to x` as an alternative to nassi-schneiderman or flowcharts. Is this what is meant by literate programming? – James P. Sep 07 '11 at 19:51
  • You're the only one on this page, who mentioned Knuth's literate programming - makes me wonder under what rock the rest of posters lived for last forty years... – cji Oct 24 '11 at 21:43
  • @James: buy a copy of Knuth's "Tex - the program" and read it. This is literate programming. – cji Oct 24 '11 at 21:50
10

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.

Morgan Herlocker
  • 12,722
  • 8
  • 47
  • 78
10

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

Mike Dunlavey
  • 12,815
  • 2
  • 35
  • 58
  • 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 07 '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 P. Sep 07 '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 08 '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 08 '11 at 16:37
10

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

Cos Callis
  • 121
  • 4
  • Why not do it and take the money? Are you so sure that your only value likes in producing code like a monkey? – Bill K Sep 07 '11 at 15:15
9

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.

James
  • 4,328
  • 3
  • 21
  • 25
8

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.

moonflash
  • 101
  • 2
  • I've been trying to get Cucumber in use in my shop for a while... unfortunately, (or maybe fortunately!) my boss doesn't care what happens behind the scenes, as long as it works. Just getting him to understand the benefit of writing tests first was an uphill battle. – Jason Lewis Sep 08 '11 at 15:13
6

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.

back2dos
  • 29,980
  • 3
  • 73
  • 114
6

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.

HLGEM
  • 28,709
  • 4
  • 67
  • 116
6

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!

John Tobler
  • 436
  • 3
  • 7
  • 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 07 '11 at 09:26
6

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.

Rei Miyasaka
  • 4,541
  • 1
  • 32
  • 36
6

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.

Ingo
  • 3,903
  • 18
  • 23
  • I was going to make the same suggestion. The boss doesn't want a conceptual overview, he wants it line by line so it should be possible to crank out something in a day or so that creates utterly useless but superficially correct documentation. It wouldn't matter if it were a rats nest of if-elses in perl that was easily confused by corner cases, it would just identify variable declarations, modifications to variables, method calls etc (remember that it's line by line, it in no way *groks* the code). – PhilDin Sep 08 '11 at 09:33
  • Yes, this boss is just ignorant. He does not know what "abstraction" is, he does not know that english is not good for expressing computer programs, he cannot imagine that he really does not want to know all those details, that's why he pays a programmer. Therefore, he deserves a lesson like this. – Ingo Sep 08 '11 at 09:44
5

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.

Lightness Races in Orbit
  • 8,755
  • 3
  • 41
  • 45
4

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.

Tom Au
  • 893
  • 7
  • 17
  • 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 06 '11 at 17:58
  • I'll bet the person writing the checks at this company would not be happy this manager was wasting this much company resources. – JeffO Sep 06 '11 at 22:28
  • @Jeff O: Could be. Or it could be that the WHOLE company is like this, all the way to the top. – Tom Au Sep 06 '11 at 22:46
4

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.

Inoryy
  • 101
  • 3
  • This may be the most constructive suggestion so far. Behavior-driven development is designed to meet exactly this need: to help programmers and their managers / clients agree about what the software does. Writing the descriptions helps with planning the code, and running the tests proves that they are still accurate descriptions. – Nathan Long Sep 06 '11 at 20:53
4

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.

Peter Mortensen
  • 1,050
  • 2
  • 12
  • 14
Andrey Agibalov
  • 1,564
  • 2
  • 15
  • 25
3

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.

btown
  • 101
  • 2
  • This is one of the most useful answers I have seen for the question. I did actually try using docco, but found it was having issues with some of my existing comments, and rendered incorrectly. I therefore went with JSDoc instead, and followed google's guidelines to generate the documentation. Not as pretty, but very much complete, and also a standard format. The problem with docco for me is that you need to structure your code to suit the comments, or it does not make sense. Thanks for the suggestion. – Billy Moon Sep 07 '11 at 07:40
3

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.

ddyer
  • 4,060
  • 15
  • 18
3

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

Peter Mounce
  • 101
  • 2
2

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.

tylerl
  • 4,850
  • 21
  • 32
1

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

John K.
  • 121
  • 3
1

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.

Joost Schuur
  • 591
  • 4
  • 6
1

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.

Peter Mortensen
  • 1,050
  • 2
  • 12
  • 14
developer123
  • 79
  • 5
1

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

Peter Mortensen
  • 1,050
  • 2
  • 12
  • 14
Dinesh Kumar
  • 297
  • 1
  • 2
  • 6
1

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

Peter Mortensen
  • 1,050
  • 2
  • 12
  • 14
Sam
  • 559
  • 5
  • 11
1

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?

Yeodave
  • 101
  • 3
1

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.

Iggy
  • 1
  • 1
1

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

Incognito
  • 3,458
  • 2
  • 25
  • 38
  • 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 04:41
0

This may be a dumb thing to actually do, but could you put together a compiler that compiles whatever language(s) you're using into English "prose"? You could run your code through the compiler, use something like wc to figure out how many lines it is, and then make it available to your boss (perhaps threatening to print it ;).

compman
  • 1,387
  • 13
  • 21
0

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.

Michell Bak
  • 101
  • 2
0

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?

Paul
  • 1
0

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.

James P.
  • 1,223
  • 2
  • 9
  • 19
0

You could also suggest a move to Literate Programming and COBOL or FORTRAN since https://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.

Community
  • 1
Kheldar
  • 219
  • 1
  • 7
0

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.

Peter Mortensen
  • 1,050
  • 2
  • 12
  • 14
whitehawk
  • 101
  • 1
  • Whitehawk, commenting has its place. Lately, the best practice has been to write code clearly so that commenting is less needed. The problem with commenting everything is it violates DRY resulting in two sets of codes to maintain--the actual code and the psudo code comments. Imagin how much trouble there's going to be when the boss insists that something works one way when it doesn't (code changed and comments not, or the boss simply misunderstood the comments). – user179700 Sep 09 '11 at 06:14
0

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.

Dave
  • 101
0

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.

Peter Mortensen
  • 1,050
  • 2
  • 12
  • 14
Petter
  • 1
0

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.

Peter Mortensen
  • 1,050
  • 2
  • 12
  • 14
Shawinder Sekhon
  • 1
0

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!

Peter Mortensen
  • 1,050
  • 2
  • 12
  • 14
bool.dev
  • 137
  • 6
0

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.

user179700
  • 173
  • 6
0

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:

thSoft
  • 109
  • 5
0

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.

Rikon
  • 101
  • 3