I have recently joined a startup in software engineering, and my tasks consist of writing code that gets merged into the master branch. Before the code is accepted, it is reviewed by my manager, who is also a founder of the company. One piece of code that I wrote addressed quality issues in a component that the manager wrote some time ago. The component is tailored to a specific scenario and needs manual tuning to work satisfactorily. After much work on the issue, I changed some of the functionality, and I documented many of the "hidden" assumptions in the new and existing code that would help the next person that would have to deal with the manual tuning process if the scenario changes. After the review, the code functionality was unchanged. However, the documentation about the assumptions was removed without explanation by the manager. I am wondering how to proceed in this situation.

  1. One interpretation is that the manager does not want the code to "look" bad. Then it would not make much sense to ask why the documentation was removed; since then, I would get no answer or some pretext answer, and I would only upset my manager. The lesson learned is that the code documentation should not be too detailed on the deficiencies.
  2. He removed it by mistake. By asking about it, he would appreciate my diligence.
  3. There is some company coding policy I have misunderstood.
  4. The manager is embarrassed that I pointed out flaws in the code he wrote but values the improvement nonetheless.
  5. The manager thought the code documentation added no useful information or that the information should be documented elsewhere.

I'm unfortunately more inclined to (1), but I am wondering if there are any other aspects I am missing.

Question: In any case, is there anything for me to gain by asking the manager why the documentation was removed?

Edits: more interpretation thanks to comments!

  • 10
    Why wouldn't you ask your manager? If there is something wrong with the type of comments you wrote, you want to make sure you don't repeat that mistake in the future. If you can't ask about changes the manager knows are obvious to you, then you need to work on improving your relationship with your manager so you feel comfortable seeking their guidance.
    – ColleenV
    Aug 8, 2022 at 16:57

1 Answer 1


"In any case, is there anything for me to gain by asking the manager why the documentation was removed?"

Definitely - if they removed the docu not by accident but for any other reason, you can safely assume that writing documentation in your code is wasted effort on your side and you can deligate your time to something else (FYI - I'm a fan of thorough documentation and comments - when you, after some months, or somebody unfamiliar with the code needs to work on it again it helps a lot to get into what is actually going on).

It might also happen that code that gets into production is automatically parsed and any comments removed (automated process) - keep that in mind before assuming malacy..

Additionally, you also get the insights of your boss/manager's/company's view on coding practices and might get a chance to throw in your 2 cents.

In regards to:

"and I would only upset my manager."

If any manager would get upset about such a request for clarification from their inferior, it would raise a big red flag IMO.

@ColleenV's comment is also good advice - if you don't ask, you can't improve/learn.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .