154
votes

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.

1

50 Answers 50

Reset to default
1
2
1
vote

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.

1
vote

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.

1
vote

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

1
vote

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?

1
vote

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.

1
vote

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

1
  • 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, 2011 at 4:41
1
vote

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

0
votes

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

0
0
votes

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.

0
votes

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?

0
votes

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.

0
votes

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.

0
votes

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.

0
votes

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.

0
votes

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!

0
votes

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.

0
votes

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.

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 9, 2011 at 6:14
0
votes

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.

0
votes

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.

0
votes

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:

1
2

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