How can I ask my boss (in a polite way) to comment his code?

Question

I am being taught by my boss (I just finished school and he wanted someone with a little programming experience, so he chose me to train me on what that company specializes in) and started working with ASP.NET MVC applications, some HTML and CSS. I'm fine with the web design stuff he gives me (it is pretty simple to understand without clarification).

But for instance, he gives me a task to do with ASP.NET MVC, he explains it really well. But he doesn't explain anything in the code he has just given me. (We use source control in Visual Studio 2013), so it's literally hundreds of lines of code, without any background on what it is supposed to do. The kind of code that I'm seeing is code I've never seen before, so it is really difficult to try and figure out.

I would try and ask him more questions, but he is always working (it's his own business), and I feel as though he might get annoyed with all these questions I have on my hands.

So just something that will help my out until I get a grip on things, how can I ask my boss to put comments into his code that he gives me, but politely?

Answer 1

You're in the 'deep end' and, in my opinion, that's the best way to learn. Not because you're looking at stuff you don't have a clue about, but because it forces you to be more resourceful and find out what components play which role in a system you're new to.

It doesn't help that your boss is too busy to handle somebody who is inquisitive (and you're totally within your rights to be inquisitive; you're keen to learn, which is good). But, unfortunately, asking your senior to change their style and approach for the sake of your learning may not go down too well, especially since you're dealing with somebody you say is busy.

Being sat in front of thousands of lines of code you're not familiar with is the norm. You can't always have it explained in black and white with comments. However for the sake of learning while you're new to it, if you feel you definitely have to ask him for comments - maybe explain why. Explain it's because of the fact you don't want to bother him with questions as he's often busy. Not only will this come across a lot less like you're telling him to do something, but it also opens the floor to discussions on how he might, instead, prefer to put question asking time aside.

Answer 2

First, crawling through thousands of lines of unfamiliar code and feeling lost is how every software project is, everywhere, from the beginning of time.

The biggest difference between you and an experienced programmer is that you aren't used to it.

---

A few points to keep in mind:

1. With enough effort, every bit of code is understandable. A lot of people feel frustrated if they can't figure something out within a few minutes. Be more patient than that.

2. A good boss is as open as possible to interruptions and questions. A good employee tries as hard as possible to minimize interruptions and questions. Be conscious of that.

3. Interruptions are more costly than questions. You can make better use of your time and your boss's time by consolidating your discussions, and by never ending a conversation feeling confused.

4. Your boss is a better programmer than you. (Probably.) That's not to say that you can't be stronger in some areas, but overall his expertise is greater. Until you have a lot of experience, make sure you're learning from his expertise as much as you can.

5. If you're sure that more comments would significantly help the code, ask your boss. "It's difficult for me to understand what is going on in some places. When I do figure things out, do you mind if I add comments?" Maybe he hates comments. Maybe he'll love it. Maybe he'll be indifferent.

In the end, however, it's possible that a couple months from now you'll remember asking this and think, "Huh, I wonder what I had a problem with? This isn't that bad. Hm, well, no matter."

Answer 3

If your boss has no time to answer all of your question, why do you think he will have time for commenting his legacy code? And moreover, what makes you think his comments would really describe the bits and pieces you do not understand for now? To my experience, trying to change your bosses programming style by just asking him will not work, politeful or not.

Best thing you can do in such a situation: comment the parts of the code you need to understand to do your work by yourself - once you have understood those parts, of course, and after getting a commitment from your boss that this will be ok. If you or your boss fear you could break something by adding comments, add those in a separate branch and ask your boss if he will take the time to review your comments before they get merged to the trunk. Since your boss has only a restricted time budget, try to figure out what a certain part does first by yourself by investing a reasonable amount of time. If you really get stuck, write your question down to a list and ask your boss, for example, once a day instead of disturbing him any 30 minutes. To my experience, this approach works with most people, even if they are very busy, as long as they are willing to help you - which is surely the case in your situation.

This way, you are sure you get the comments you need, and your boss will see where you need additional information, and if you got things right. And as long as you restrict yourself to comment only the non-obvious things, there is a good chance your comments will increase the overall quality of the code base, which might not only bring benefit not just to you, but also to everyone else who has to deal with the code, including your boss.

Answer 4

Firstly let this be an example to you to comment your code properly, grasshopper!

Then, I have to do this all the time. I have my local copy checked out, and I go through it and comment it myself. (I can strip them all back out again if I am going to check it back in - or leave them in, if nobody minds.) Then when I really can't see further, I can ask someone, here, I think it does this (what I commented), am I right? So you may have done the actual commenting, but it's done and that's the point.

Answer 5

This is more than just a personal request. You are trying to change habits / culture, and that is not easy. It's certainly not something that can be accomplished by a hallway conversation or an e-mail. It's going to take some effort on your part.

Be the change that you wish to see in the world.

The quote may be falsely attributed to Mahatma Gandhi, but it's applicable advice. As you try to puzzle out the codebase, write the comments that you would like to have seen, to the best of your ability, and commit them, after being reviewed by your boss. Advantages:

• You're being proactive, rather than nagging.
• You're setting a good example. In the best case, your boss / team will see the benefits and follow suit.
• Some of the comments will probably say /* Mystery parameter 3 */ or /* 2015-02-09 AidanQuinn: Is this code ever called? */ — those are opportunities for your colleagues to either document the code properly or fix latent bugs.
• If, during the pre-commit review, it is discovered that a comment you wrote is inaccurate, then your colleagues now know that the code was unclear.

Refrain from any rewriting or refactoring as you do this, and the introduction of comments should be nearly risk-free. If you do rewrite anything, keep those changes as separate commits.

(Before you embark on this project, though, be sure that your expectations for comments are reasonable. If your idea of well-commented code is outside the norm (Example 1, Example 2), then you'll only be making a fool of yourself.)

Answer 6

I wouldn't ask for additional comments, but here are some ideas for you:

1. Schedule a sit down with your boss and have him go through the code at a high level. This should get you started. I would expect a few hours to maybe a half a day so you can get up to speed. This should include overall design, patterns used, etc.
2. Create a tests project and start writing unit tests against the code, this will help you understand it without impacting it. You may also find some bugs as well!
3. Debug the code as needed to understand certain areas.
4. Take an enhancement or bug off the backlog and work on it.

Comments are OK, but if the code is written in a straight forward manner it should be understandable after a few days.

Also don't expect to understand it all, it is better to focus in on key areas first and then expand code base knowledge as needed.

Answer 7

I have been in a very similar situation to yours roughly a year ago. I started working with little programming experience (though I knew a bit of OO and some other languages to begin with) and the one person teaching me had very little time. He was always helpful, but I felt like I wouldn't want to ask every single question I had.

Others have already suggested extremely helpful stuff here (writing unit tests for example, but from my own experience, that is something that would have gone a bit 'too far' for me from scratch; or commenting parts of the code yourself, but that may be difficult depending on the first point/question I'll be asking you in a minute). The following points sum up what I did and what helped me, but it depends a lot on where exactly your problems lie.

Also, I have to agree with @AK_ who said that you don't really need comments in C#. That may not be 100% correct (I feel there's areas where comments definitely help, e.g. Reflection-heavy code) but in essence it is. If you write really 'clean code' with well-named methods and variables, and have lots of small 'bites' of code, they will be almost totally unnecessary. Everytime I felt the need for comments when reading code so far, then after I understood what it did, I was very unhappy with the way it was done and thought it could have been way clearer in the first place by good refactoring. Edit: I'm specifically talking about C# comments here, not documentation (be it separate documentation or XML comments), as I think that documentation is always important.

• Identify what exactly your problems are and if you can categorize them. That is, do you still have problems with the language itself or don't understand a specific syntax (e.g. lambda expressions and LINQ in general, or Reflection)? If you don't understand lines of code, you won't understand what the whole method/block does, so commenting it yourself will be hard. Rather, get a good book ('C# in a Nutshell' it was for me, but I heard 'C# in Depth' is spectacular as well) and read up on the things you encounter. Categorizing these problems beforehand makes this easier, as you can fill 'bigger gaps' at once, or even ask your boss about it, as it's not lots of questions anymore, but rather explaining a single subject or the most commonly used constructs so that you can get a huge 'boost' in this area quickly.

• Parallel to the above, I tried making myself familiar with 'clean coding' and best general practices (not language specific). The effect of this may not be immediate, but it will pay off sooner or later, either when you have to extend existing stuff or wonder why someone created so many small methods instead of one where everything is contained ;-)

• Get a grasp of common design patterns. They may be appearing here and there in the code you're reading, and if you recognize them it will immediately give you an a-ha moment. Even if you understand what the code you see there does, it may make you wonder why it is done this way, and figuring this out all by yourself is often not that easy.

Please don't take the above text as me making assumptions about your 'skill', I often accidentally switch between talking about my experiences and talking 'to you'. It's mostly meant as what I encountered, and what I did. As others have said, this can be a very good experience and it's pretty much the standard in the job to read code that's not your own and that you don't know much about beforehand. But it can be really satisfying to finally grasp what's going on there and recognize yourself getting better at this particular 'skill'. Take this as an opportunity to learn a lot in really short time, good luck! :)

Answer 8

You are probably not going to get him to change his style.

What you can do is ask lots of questions, and write down the answers.

I inherited a huge code base at my last job, little documentation and few comments. So I would try for half an hour on the same problem, then if I still couldn't figure it out, I would go ask someone who either wrote it, or knew how to use it. Then I would document all the things that he told me. Most went in our documentation, some went in the code as comments. After a year there I had practically written a large portion of our documentation and I knew a lot about the code base.

Good luck!

Answer 9

I was having the same problem. Im student of phyzist and have good programing experience. I was programing in many languages but nothing for premium aplication.

I have applied for a job for web developer and they instantly put me on back end of web programming. When boss showed me the base api for node REST application i was thinking that I would throw out. I have never seen functions with callback and so strange syntax. And I ask my boss do I have a problem If i don't understant anything in the code. He sad no, he sad that i have 1 month to figur it out and in the mean time I will make a CMS for testing me with another frontender.

Well and I went 1 line of code at the time and google every thing that I havent know. So 1 week was passed and i was familiar with the code enough that i could make some colaboration with front ender. My code at the beginig was crap but se me 3 month after that! I'm coding better and faster than our software architect !

I sugest that you never stop learninig! My moto -> Keep learning and keep calm :) Dont depend on boss be independat and ask him directly but only the hardest problems. Because you will be happy after you figure it out by your own resarch. And remember when you stop learning its something wrong, learn ewery day how to be a good programmer.

If you will learn from boss you will never go better than him set your own standard, learn blind typing, VIM or VIM plugin for your IDE, Linux wmii, so you would some day go beyond of boss, and be better than him!

Answer 10

As a software engineer of 20 years standing, mostly working on safety-related stuff (SF-PD), I'd have to say that your boss may not the person you want to be your example. Lack of comments is a sign of either a self-taught amateur coder who's never learnt how to do the job properly, or an inexperienced engineer. Or perhaps an engineer who simply doesn't have the time - deadlines and expediency can do horrible things to your code! ;) It's definitely an anti-pattern for every competent software engineer though.

Your boss might be a very good coder, but it sounds like he's not a good software engineer. An engineer uses collective group experience to avoid the pitfalls that other people have already been caught out by. Effective commenting is part of that collective group experience for software, in the same way as stress analysis is part of the collective group experience for mechanical engineering. What counts as effective commenting is more fluid though, and it's definitely something you get from experience.

The most basic thing is that comments should not say what a line of code does. There are times when comments to say what a function does are superfluous too (especially in C#). Over-commenting can be just as ineffective (and a pointer to lack of experience) because you can't find the important stuff in the dross. As a novice, you may still be working on figuring out the "what" of the code, and for that you just need to read and understand what he's done.

The important thing for comments though is that they say WHY a line of code or a function does what it does, where this might not be obvious. Do you need to set up module X before module Y? Is it important to check a return code to see whether a file was already open, or are we consciously ignoring the return code because this has been checked somewhere else? The "why" of the code will be relevant to everyone, regardless of experience - and it'll be relevant to him as well in 6 months time, when he's forgotten about the good reason for doing something a particular way. Commenting isn't just for other people, it's for helping you in the future as well.

If you want to avoid annoying your boss, ask smart questions. Focus on asking about the "why", and try to work out the "what" yourself (unless it genuinely is obscure). No good boss will mind being asked questions if they aren't the kind of things that you could have found from R-ing TFM. And no good engineer will mind being asked to do something that'll make another engineer's life significantly easier, at little cost to them. (Just don't ask him to backfill comments on the entire codebase! ;)

Answer 11

Been in the similar situation, I'd say

1. Your boss might want you to learn the dirty way (by walking through the code that you have no clue of) for a reason. This is the way we learn more in a month at work than an year at college as mentioned in other answers.

2. This is "the norm" as mentioned in other answers. You should be more worried about where to start and how to approach and what to focus on than trying to understand every line of code right away. Ask your boss about the right tools and ways to debug/step through the code. This kind of questions will buy you some points.

3. On regular basis, keep approaching your boss for feedback on how you are doing so you'll get an idea where you stand in percentile terms assuming your boss have seen good number of people in the same situation and have an idea how they did.

4. Take this as an opportunity and as you get better with understanding the code, keep adding comments that you originally expected to ask your boss.

Answer 12

If you really want to try to ask him to put comments in his code (I don't recommend it) I would suggest finding code that you need to edit that could really use some comments (most is self explanatory) and asking the question about like this "I was looking at this code here and I'm trying to figure out [Issue you're having] and I couldn't find any comments to help explain it". Basically try to show that you've put effort towards understanding it and explain why it is that you both could benefit from comments being there.

Probably 90% of well written code doesn't need comments. You only really want to document the parts of code that have been optimized and have become rather tense. I worked at a company once that required you to document every piece of code you modified basically the comments ended up being actively detrimental to code readability because they often referred to code that had been removed or modified beyond recognition. Beware of poor comments I spent a week debugging a function and in the end I found that the comment I kept reading about setting such and such a flag to "false" was actually the whole issue I set the flag to "true" and everything worked as it was supposed to.

Answer 13

If you want comments in the code to understand why something has been written then most likely (considering you are new) you don't yet understand the business needs. I'm sure you know all the syntax and can read code but unless you know the purpose of some code then you will feel a bit lost.

One thing that springs to mind is pair-programming. You say your boss is impressed with your progress so you could suggest working alongside him. This will help both of you in the long run. Your boss will find himself having to explain things he takes for granted and you'll learn more about the business.

Answer 14

As others have mentioned, this is quite common, but that doesn't mean you just have to suck it up and plow through. You don't need to understand as much of the code in as much depth as you think you do, and there are concrete strategies for making the "deep end" a lot shallower:

• Find something in the code related to the task at hand. Usually the easiest to search for is something user visible, like the label of the button on the GUI. Write down where you found it. This will be your anchor point.
• Now search for code one step away and write that down. Who creates the button? What code gets called when the button is clicked?
• Source control is often useful for finding code that's one step away. Find when the code you're looking at was added or changed, and look at what else was checked in at the same time, and why.
• Repeat until you understand just enough to make your change, plus one level deeper to make sure you aren't missing anything.
• If you get stuck at any point, you now have a very specific question to ask. For example, "I can't figure out where this button gets instantiated from."

Answer 15

Here are my $0.02 on the matter. I'm not suggesting an exclusive answer, a lot of what has been said here is quite relevant.

I would try a bit of social engineering to arrange things so that your boss finds it easier/less time-consuming to comment some of his code than not to.

Now, this can be pretty easy if you were willing to take a big risk and annoy him - but we don't want to do that. (side note: You could just fail to be able to do anything without him writing down or dictating comments to yo, you insisting and pestering him about it endlessly etc.)

What's the alternative, then? A few ideas, depending on the circumstance.

Option 1

1. Take the time to understand a piece of his code as doing X.
2. Now think of a reasonable way Y to misunderstand it.
3. Tell boss (via email or say over breakfast or what-not) that you're currently trying to figure it out.
4. Add a comment saying it's not clear what the code means , but you understand it as Y; try to make this comment visible to him - but don't try too hard!
5. Act assuming Y - and make sure your boss notices your action (so you don't waste your time work for a long time on a false assumption).
6. Boss should take the initiative to correct you. At this point, tell him something like "I really wish this code had a couple of comments to prevent me making the wrong assumption. I'll correct the comment I added for myself. Do you suppose you could help me out with some general description of this-and-that pieces of code? I'm not experienced enough to figure out the exact intention, and I'm just a couple of sentences would do the trick." Or something..

Option 2

You're in training. Try to arrange for an (additional?) fixed-frequency weekly meeting with him. At this meeting go over some code - but you need to come prepared enough for him not to have to explain every single line. At some point - hopefully - he'll realize he can skip the meeting if he just added the comments.

Option 3

Get another co-worker to fail to understand the same piece of code as you. Both of you approach the boss at different times asking the same questions. That's a sure-fire way to make him realize he's failing to do something... but not everyone has the luxury of helpful coworkers on the same project.

Answer 16

So just something that will help my out until I get a grip on things, how can I ask my boss to put comments into his code that he gives me, but politely?

If you can't understand the code, why you think the comments are your solution?

I don't know his programming style, but I admit that if the name of functions and variables are misleading, it makes understanding a code very hard. But if names and functions or even the organization of the program (classes, methods, properties...) are so that make the code understandable, then the code actually will talk to you by itself.

You'd better ask him for the program architecture and if you want to request him for something, request for some more meaningful names for functions; that is more convenient for him to do.

Answer 17

Even if there is a way to ask this politely, there are two possibilities as to what your boss will think about comments in his code:

1. Either that comments in his code would be a good thing to have, or

2. That comments in his code would not be a good thing to have.

If your boss thinks that comments in his code would not be a good thing to have, (and there are very good arguments for this, i.e. the code is supposed to be the documentation, and no documentation will ever stipulate something as precisely and as unambiguously as the code that actually does it,) then nothing will happen.

Now, if by any chance your boss thinks that comments in his code would be a good thing to have, then there is a considerable chance that he will tell you to study his code, understand how it works, and proceed to add comments to his code yourself. (There are very good arguments for this too, i.e. you need to learn, and his time is by definition much more valuable than yours.)

So, unless you are prepared to have to do this, you might be better off not saying anything.