More junior teammates don’t understand my work...and that’s my fault?

Question

I’m a software engineer and the most experienced within our team. My code has been labelled as “complex” and “hard”, by both my junior colleagues and (vicariously) my manager.

My code is “complex” because it’s well engineered. It’s like that for many good reasons, which make it easier to read, refactor, test and maintain. In my opinion — at the risk of getting defensive about it — it’s actually easier to work with than the piles of spaghetti that my colleagues churn out. Don’t get me wrong, I’m sure it could be better, but I’m effectively being criticised for doing an objectively good job.

I’m not “gatekeeper-y” about it either. Whenever my colleagues ask for help to understand why I’ve done something a certain way, I happily explain and attempt to do so in a constructive, patient way. (e.g., I’m not dismissive and take the time to understand their point of view so I can get them from A to B.) Sometimes I don’t have time for this — I have work to do, too — but I’m never rude and always try to make time when I can. Failing that, my code is generally well commented and documented, so if all else fails, my colleagues have the means to help themselves.

Until I pointed out that the techniques I use are best practice and there for a reason, it was even suggested that I “dumb down” my code! To be honest, I’m actually quite upset about all this. What else can I do?

---

EDIT I’m beginning to regret writing:

My code is “complex” because it’s well engineered.

...as it seems to be being universally interpreted as arrogance. I can see why, but I wasn’t trying to be arrogant nor closed-minded. The scare quotes are important in that sentence and I can justify my assertion with evidence, but that isn’t relevant to my question. Rather, I had hoped my narrative about going to lengths to help juniors understand exemplified this.

Answer 1

I did a series of talks on what makes code simple and readable. There is no absolute answer. Much depends on the vocabulary the reader brings. Take for example:

bool retval;
if (x > 0)
{
   retval = true;
}
else
{
   retval = false;
}
return retval;

Compare this to

return (x>0);

To the complete beginners it's possible the first seems simpler, more straightforward, more readable. It's actually super error prone and hard to read. The most important thing (what controls whether this returns true or false) is surrounded in a sea of much less important things. A person could accidentally set retval to true in both places, or false in both places, or return an unrelated variable that happens to be kicking around. I can explain at great length why the single line is, in my expert opinion, simpler and more readable.

None of that will help a junior who is not used to boolean expressions and has little or no experience writing in whatever language you're using. Thus, you have a problem. The solution to your problem is not to say "well, whatever, I know my way is better, these developers are just not good enough to know that." You've been told to write differently, and you don't want to, so you're going to need to get them up to the level you need them at.

There are lots of ways to do this, but a nice one is to pair on refactoring (or even to mob) every once in a while. Say on a Wednesday afternoon. Find a piece of code you find hard to read, decide how you would make it better, and then walk them through it. Point out things like "if you change the tax rate, you'll have to edit here, here, and here. I want to make it so that we don't ever change just two of the three places." Walk them through why it's better to do X than Y. Focus repeatedly on the benefits. For example, in a typical C++ for loop there are SO MANY places to make a mistake: did you start at 0, are you checking the right end-condition (< vs <=), are you incrementing properly, etc etc. If you use a range-based for, much of this falls away and you can't get it wrong. If you want to touch every element of the collection, the range-based for is just flat out easier. Be nice - start with "this code works, and the tests all pass. It's not broken. I want to show you how to adjust it so that it's more maintainable." (Or whatever.)

I expect you'll be working at a higher level than replacing verbose if/else statements and using modern loops, but you can take a similar approach to whatever abstractions and patterns you're using in your code that people can't understand on sight. Show them how to transform their code into something that has benefits like being easier to modify, or more clearly expressing intent, or whatever. Where you can, prepare resources where obvious experts say to do it your way. (For example, in C++, you could cite the C++ Core Guidelines, co-authored by the inventor of the language and the convenor of the standards committee.) Teach them the vocabulary that you're using in your code and they will be able to read it -- and eventually to produce it.

When you teach juniors how to write better code, you not only make your day-to-day life easier, you make the world better. But stay focused on the first part, your day-to-day life. Get them up to speed and you won't have to spend time wading through their spaghetti code, or arguing about whether your stuff is too complex. You'll save time overall, and instead of being seen as a grumpy over-engineering fan who writes things no-one else can read, you'll been seen as a generous teacher who lifted your coworkers skill level dramatically.

Answer 2

Disclaimer: this answer will be written as if OP's coding style really is as complex as necessary (not over-complicated) and it's really good, efficient code (not something that could be done easier and in a more understandable way with the same result).

I think I was in your position before. I was the "expert" guy working on integrating and developing various systems in my company. It was a complex task, really pushing my limits of understanding. So when we got 3 new juniors to help me with the workload (I was working alone before), I quickly noticed that they struggle to understand what I've written or even what problem I (well, now WE) am trying to solve.

My solution was going to my boss and explaining him the following: for the next 3 months my personal output will be reduced, probably to near 0. I will use this time to make sure we have 4 skilled people on board, not 1, as this will ensure any of them can pick up my work if a certain bus would run me over. I prepared a plan, got it accepted (you need to have your managers onboard with you on this one, he will be able to explain it better to the higher ups as well as have more pull for your plan to be accepted).

I then set up the following scenario:

• I would assign a task I would normally do to one of the juniors. I would invite him for 1-on-1 with me, as I know some people may have hard time to focus and perform when they are watched by others and failing (and fail they did, but it was expected, it wasn't anything bad).
• I would take a similar piece of solution, delete it, and work my way up explaining every step: what I'm doing, why I'm doing, what I am trying to achieve. I did not provide documentation. Instead, the juniors task was to make notes how he/she understands what I'm saying.
• After that, I would pass the keyboard, we would go back to original problem the junior was assigned. Using instructions he wrote and my help, he would now try to recreate the solution, now his turn to explain me what, why and how he/she is doing the things.
• After that, the next one would come for 1-on-1 with me. The previous one would have a task to redact and post his version of the documentation over the next 2 days so that we have a second version of it from a juniors perspective.

The result was the following:

• The team was not intimidated by tasks, they knew they were learning, not being put to the block so to speak.

• I (think) set up an environment they could comfortably learn with no judgement or anything. Even if they had absolutely no understanding of what they are looking at first, after the first month they could work reasonably well on their own, I would barely need to interject during their time to code.

• We now had 2 versions of documentation: their version, being "If you see it for the first time, here's the beginner version for you to understand, with everything in simple terms" and mine, being "if you grasped the basics, here's some interesting details and advanced information".

After those 3 months, I had a team of employees able to work on their own, collaborating on documentation, helping each other understand the last bits of missing info (as they wrote their own docs, they were the best people to explain them), not afraid to tell me they need help with something.

And above all else, I had trained people that by the time I left could equal me in in my work.

Answer 3

You have junior teammates, and your organisation needs your code to be comprehensible to them.

This is critical. You've been given an unwritten requirement - your code must not only do the job, but it must also be maintainable by others.

This is a very difficult balance to play. Compare the abstract factory pattern with a simple hash table of factory callbacks. Both do the same job. But the former is much harder to explain and takes additional training.

There are further issues if you're using a complex language or framework.

You mentioned in a comment that you are using python, and not using any complex frameworks. So it sounds like your code itself is the problem. I say problem, mainly because (although this depends on how many opinions you have sought here) several people are having a hard time understanding your code.

Your only way forward may be to dumb it down. Don't take this to heart - a great thing which only you can appreciate is not as useful as an Ok thing which anybody can appreciate.

You'll thank me in the long run when people stop asking for help with your code!

Answer 4

My code is “complex” because it’s well engineered.

Failing that, my code is generally well commented and documented, so if all else fails, my colleagues have the means to help themselves.

And yet what you call well engineered and documented code is being considered as hard to work with.

Those are contradictory statements, as code that is well engineered and documented, even if solving a very complex problem, is going to be relatively easy to follow and understand. The domain knowledge it captures may not be so easy to understand, but code representing it certainly can be (with some exceptions but they do not seem to apply to your problem).

The fact that you have an outstanding occurrence of needing to explain your work is a great indicator that your code is not as well engineered (possibly over engineered) and documented as you may think, or that while it's detailed enough, it's written for the wrong audience.

Until I pointed out that the techniques I use are best practice and there for a reason, it was even suggested that I “dumb down” my code

I'm going to guess that by "dumb down" you mean "simplify the engineering". Dumbing down would mean removing/reducing functionality.

What else can I do?

Since this now went up to the management who took side of the juniors start by taking a deep breath as whether you like it or not, there is a problem with your work and it's not meeting the expectations of the team and your manager.

You will likely have to compromise, and arrange for more time to train those juniors (though this takes months to train up a junior) while making your code more accessible at the same time. This can be done in code itself by breaking it down into more digestible chunks/wrappers, or by writing a documentation that targets the correct audience - junior, not senior, developers.

I would also take a good honest look at your own work to see if it's really well engineer, or simply over engineered and too complex for what another solution could do. While it's tempting to always use the technically "best" approach, often enough it doesn't make much business sense, and something much easier and simpler will do just fine while also making the codebase much more approachable.

As the old adage say, perfect is the biggest enemy of done, and it seems to me that your strive for engineering perfection is getting in the way of juniors done.

Answer 5

TLDR: IF nobody else can follow your code, it is you who is the one who is in the wrong, PERIOD

When I was a noob, first year of programming professionally, the company had hired three contractors, myself, and two others. One of them was an absolute genius.

Two full-time jobs were offered, and the genius didn't get it. Know why?

Not even the other two full-time employees could follow his code.

A programming team is like a choir. If you're the one with perfect pitch, and the entire rest of the choir is flat, guess who is wrong?

Yes, YOU understand YOUR code. Virtually every coder can make that claim. If you are in a team environment, that doesn't help anyone.

Assuming you are the team genius, it would be easier for you to do it THEIR way than for them to learn yours.

WHAT YOU SHOULD DO:

Get a feel for where your team is, skill wise, and bring them up SLOWLY to your level. Teach them ONE technique at a time, and watch as they come up, then bump it up a notch.

You can turn a bad thing into a good one by becoming a mentor, and lead to the less skilled, and instead of being the proverbial millstone around the team's neck, you can be a leader. Very useful on a resume, BTW/

Answer 6

There are two possible reasons why working code is hard to read: Either because something easy is written in a much too convoluted way, or because something complex is written in the best possible way. (Being a difficult problem AND written in a much too convoluted way AND working isn’t possible simultaneously).

I’ll give you two examples of complex problems: 1. Optimal limited length Huffman codes. Quite simple. Given a set of symbols with probabilities find an optimal Huffman code with the additional restriction that no code has a length > n, for example with n = 15. 2. Modify the heap sort algorithm so that it runs significantly faster for a sorted or almost sorted array. (I think Edsger Dijkstra did that). The solutions for both these problems are hard. Understanding them is about at my limit. Writing these algorithms would have been beyond me. And creating a solution _that is easy to understand _ is something nobody has managed yet.

If the cause of complexity is indeed that the problem is hard, then you tell your boss that, tell him you can’t simplify it because the problem is hard, and if he doesn’t believe you, then he can feel free to find someone else to do it. I did that once, someone rewrote my code making it a lot easier to understand, and of 15 well-documented edge cases, not a single one worked after the change.

Answer 7

My code is “complex” because it’s well engineered. It’s like that for many good reasons, which make it easier to read, refactor, test and maintain. In my opinion — at the risk of getting defensive about it — it’s actually easier to work with than the piles of spaghetti that my colleagues churn out.

From the feedback you got, your code is not easier to work with.

I have seen it a couple of times, when colleagues develop their own frameworks and code styles and claimed their approach was easier to understand, only that it wasn't. As somebody who didn't know their frameworks and code-patterns, I first had to reverse engineer what their framework does, before I actually could start understanding what the actual business logic does.

This is isn't specific to homebrewed frameworks, this is true for all frameworks. If you know Spring, it appears convenient and simple, if you only know Java but not Spring, understanding Spring code is not straight-forward.

This doesn't mean that you cannot have good code in your company, but it means that you cannot just assume your code is "easier", but you have to make sure it is. You can achieve this by:

• if there is indirection (for example by using dependency injection) make sure it is easy to find the right code quickly
• don't make code that is easy to write, make it easy to read
• prefer explicit code and configuration over convention
• have junior developers review your code, if they don't understand what you are doing, explain it to them and ask them what confused them and what you could have done differently to make them understand the code in the first place
• don't optimize prematurely (whether for performance or changeability)
• make it easy to grep for code
• Follow the Open/Closed-principle so that there is less need to modify your code
• document your interfaces, so there is less need to read your code

Answer 8

Yes, you are an awesome coder. {{applause}}. But it doesn't matter. Where you've gone wrong - and all of us have at some point - was thinking that this job is about you impressing people with the quality of your code. Right now you are sitting in a high tower looking down on people but the people who run the company are down there too. This isn't good for you.

Ask yourself why your company has only hired people who can't understand your code. It probably has to do with budget. The people running the company aren't going to increase that budget just because you decided to write some new code that needs higher quality developers to maintain it. So the only way anyone is going to understand what you've done is if you teach them or you "dumb it down".

It's going to be in your interest to solve problems in ways that the business side values. The more problems you solve the better. And as you solve a lot of those problems and make the business leaders happier you will get more freedom to introduce changes that you feel are good.

But you have to do it as a mentor/friend. Not coming from a place of anger/loathing. Or move to another company.

Answer 9

I would suggest moving to another company. In my (not so humble) opinion (I've had similar discussions at past workplaces), if your manager isn't supporting you and providing the opportunity to hire better or more seasoned engineers, then you're working for a company that's trying to get by with the minimal bottom-line. But, that's not an attitude you share. Find an oranization which encouragees excellence and provides the environment to foster it.

Answer 10

I would propose a few things to ease the situation between you (a more experienced developer) and the juniors:

• Create a code-style guide and make everyone to follow it. This way junior developers can learn way faster. They can start to understand things because some explanation already exists (be it a broad one, but still).
• Like people mentioned, have some sessions with your junior or other colleagues discussing code in general, maybe even telling them to write questions before hand and asking them during that session, so you would save time.
• Best practices and so on are good, but when they start to obscure code, this is the time to consider if they're worth it. Again code-style guide for your team and or company would help.

Answer 11

The answer entirely depends on the type of company you're working for.

If you're working for a consultancy, AKA a body shop, your value is measured in the amount of work you get done, not how well you do it. Once the work for their current client is complete, a consultancy simply moves on to the next client's work. The end result is software that mostly works but will probably have a few bugs here and there, which is great for the consultancy since it guarantees future work. It's all about getting software out as fast as possible.

Despite the fact that the result is subpar software, the client will take it and happy or not, move on. This is because the type of client that uses a consultancy is generally the kind that doesn't understand that software is core to their business, and as such doesn't want to pay for software as they view it an unnecessary and wasteful expenditure - so again, speed is most important to them.

In the project management triangle, therefore, cost and time are minimised - with the result that so is quality. This has a knock-on effect in all aspects, particularly in the consultancy's hiring practices. The consultancy doesn't want rockstar developers, because it doesn't need rockstars to churn out Yet Another eCommerce Website and it sure isn't going to pay them rockstar rates - a consultancy wants plodding donkeys who can generate code at a reliable rate for a minimum amount of pay. As a result, consultancies tend to attract and keep developers that are, shall we say, near the bottom rung of the ladder in terms of competence and willingness to learn.

Standard software development patterns and practices are of course aimed at increasing developer output, but many of them require a developer who is able and willing to engage their brain. The latter is a problem for many consultancy developers.

In short, attempting to introduce good engineering to the average software consultancy is likely to cause more problems than it fixes. And things that cause problems, and hence delays, in consultancies are viewed in a very negative light, because they directly impact the amount of money being made.

A product-driven company that develops its own software, to sell to clients, has entirely different concerns. Cost and time are less important and quality moreso, because they have a reputation and a good track record to build and uphold (otherwise their clients will go to a competitor). Such a company is therefore inclined to hire better developers and pay them more, because they generate better-quality code, and allow them to implement best practices that ensure that quality.

If you are working for a consultancy, your first priority should be to escape (I use that word intentionally). Your attempts at helping your colleagues to build better software are going to confuse them, infuriate management, and make you desperately unhappy. Try to find another position elsewhere (that's not with a consultancy!) as soon as possible.

If you're working for a product-driven company, then your company has some very poor management and/or hiring practices. This could be due to many things, but you need to decide whether the company and product are compelling enough for you to stay and try to make a positive change, or find greener pastures. If you're intent on staying, then you need to figure out who makes the technical decisions there, and have a conversation with them explaining your viewpoint and how it benefits the company in the long run. Whether they listen to you or not will be the sign as to whether you should stay there or not.

Answer 12

What else can I do?

You can teach.

I am an amateur dev and my code is not nice. It is readable (at least while I have it in front of my eyes) and does the job.

Then a guy who knew how to develop joined my team (we are not developers, but we generate some code for various tasks). He had all these CRUD structures which were simply horrible - code all over files and whatnot.

I told him to "dumb down" his code so that I do not need to get a degree in CS to understand it.

He showed me why he does this. Not how the code works, but why it is structured this way.

I agreed with him and let him write code the proper way. This does not change my code (though I agree that what he does makes sense but I do not develop enough to make the effort to refactor).

I think that your coworkers do not understand the "why" of your code structure.

Note: I am assuming that your code is indeed good, clean, correctly architectured etc. and that theirs is bad, spaghetti, etc. Just make objectively sure that this is really the case.

Answer 13

I don't know the specifics of your situation but I would advise trying to educate your peers about why you're things this way.

Consider talking to your manager about setting up a 60-90 minute learning session on a weekly basis. Make it an open invitation for anyone on the team to attend, and optional. This is also helpful if someone has an unfounded complaint you can say "I went over this in the last learning session and the team came to the conclusion it was ok. I can explain it to you now, but you might consider to start attending them."

Present on a piece of code they've had an issue with and explain why the way you've done it is more maintainable, scalable, or whatever. If the solution you've designed is actually superior you should be able to come up with legitimate reasons why, and also to show legitimate reasons their proposed "easier/simpler" solutions might cause problems.

This should all be done on a non-confrontational way. e.g. don't say "Here's my solution and it does X. Your solution is bad because Y." Try something more like "Here's my solution and it does X. If your solution needs to do X, what happens?" Let them walk through it with you and find the issue of Y themselves. These are teachable moments and you can take advantage of that to help everyone improve their skillsets.

Answer 14

This is really hard to answer, as you're asking us to judge whether you are writing good clean code and the other devs are not as skilled to be able to understand it, or if it's you writing over-engineered or unnecessarily complex code.

Without seeing lots of code examples of yours and theirs this is really hard to help with.

Perhaps instead of debating the code and explaining your actions and why yours is clean etc, start discussing why they find the code hard to read. You may be justified in explaining why your code is good, but I think this doesn't matter, all discussions need to be around why they find it hard, and how they'd have written it.

Focus on small pieces of code so the debate is more about small structure than architecture (that's a different, bigger problem I think than you have).

And remember, devs can be fickle beasts at times, and invariable at others, and as most things are subjective to a specific scenario (not one approach fits many scenarios) this combination means there's always going to be discussions about "the best way" and what is right.

Maybe all parties are correct and have valid points? And you just need to find some middle ground?

Answer 15

This questions can't be answered generically without code samples and without project description. Also likely can't have an objective single answer.

I like @gnasher729's answer. But below you can find another spin.

I had a team member for short that was claiming best practices mandate implementing things in a very different way. In my opinion though his understanding of said best practice was misguided and didn't make the code simpler or more maintainable while it was introducing additional external dependencies.

Another thing is indirection. While you may consider that project is going to develop in some future direction and implement indirection beforehand (which is often found as a best practice in the books), that makes code much more complicated and this future direction may never manifest. I am personally inclined to this. While my guess is often correct, sometimes it is not and results in a harder to understand code.

Now we can't write perfect code and have our predictions always manifest. You might be right that your code is so good (I doubt it btw, because I haven't met a good programmer that likes the majority of their code), but for a change and for experiment, you can try going with simpler approaches. You can keep track of places where you did so, and later validate whether that was a good or bad idea. I guess a few months will be enough for you for a perspective.

wrt good programmers not liking their code, I think it is related to the fact that you usually you are under time pressure to deliver something working, project changes make another approach now more effective, production usage doesn't match expected usage, but also critically thinking you always find better ways to do things.

I personally find myself tuning and commenting my own old code I have forgotten about when I have to fix/extend it, because while writing, my line of thinking looks easy to follow. When I have forgotten about the code though, I have also lost this inherent understanding of what I was thinking at the time. So I tune code for readability or add comments where beneficial to make understanding it another time hopefully easier.

Answer 16

Other answers cover the main points: in a nutshell, you've got to (a) decide to what degree your code has to be this "complex" to get the job done, or is, perhaps, being "a bit too clever"; and (b) to what degree you should "come down to their level" or they need to get more training. (In reality, it's probably not a binary either-or: there's probably a bit of give-and-take on both sides).

What I will do is a suggest a way to help answer these questions... try posting some code¹ to the Code Review stack. While the responses may not be totally objective (everyone seems to have their own definition of what makes "good code"), the responses should, at least, be detached from you and your team, and shouldn't share their, and your, biases².

Specific responses and suggestions are probably less important than the overall tone of the (collective) responses. If you can read them with as open a mind as possible, they may help indicate to what degree you and your colleagues need to adapt. I suspect it will be a case of "meeting in the middle": the question is where exactly "the middle" is!

---

¹ It's likely that you won't be able to post your real project code, either due to copyright issues or not being able to take a "representative sample" of an appropriate size in isolation. If you can't post existing code, tackle a "Code-Review-size-problem" and try to write the code to solve it in as close to your normal style as possible.

² For example: are they saying it's too complicated because it is too complex, or because they don't want to spend time learning more complex techniques? Are you saying "it has to be this complex" because it does have to be, or because you are, perhaps subconsciously, trying to be "too clever"?

Answer 17

Do you have unit testing in place?

Unit testing, especially if automated, might help your colleagues to grapple with sections of the code.