Helping someone who is not and never will be a professional programmer write code that is more legible and usable to use and interpret [closed]

Question

I am Elvis, trying very hard to learn to be Einstein. I work for Mort.

What the hell is this crazy idiot talking about!?!? (You only need to read the first few paragraphs)

If you don't feel like reading that link, basically, I am a professional programmer, and my boss is (this is scarily accurate):

the professional line-of-business programmer who lacks a degree in computer science but has a great deal of familiarity with Office and VBA, and who typically writes productivity applications shared amongst his coworkers

All that said, a large portion of my job is taking his cobbled together code and making it production ready. However, the very poor style and cargo-cultism makes this difficult. This is compounded by the fact that he is unwilling to read programming books or allow me to help him refactor his code.

Are there some other strategies for helping someone who is not a professional programmer, never will be a professional programmer write code going forward that is more legible and usable for me to use and interpret?

Answer 1

In looking at your responses in several of the comments I don't know if you realize that what you are experiencing is quite common, particularly when working in specialty fields where it takes domain experts (let's call them the scientist) to figure out how to incorporate and tailor algorithms for problems at hand.

Rather than complain about the scientist and expected them to change, just realize that you shouldn't expect the scientist to care much about "code quality". It is frequently hard to get other software developers to care about "code quality" let alone someone whose main interests lie in the domain and not the programming.

Where you go from here depends largely on the degree of confidence the "scientist" has in your ability to understand their work. If they have confidence that you can understand their code and won't muck it up when you modify things then there usually isn't an issue. They'll rely on your expertise.

However, if the scientist does not want you changing their code then it is highly likely that you haven't "earned" their confidence yet. If that is the case then rather than focusing on fixing the scientist, you should focus on "fixing" yourself. What I mean by that is to take steps towards gaining their confidence. Probably the easiest way to do this is as follows:

As part of your testing process:

1. Start turning the algorithms into something easier to understand (e.g. diagrams, PDL, math notation)
2. Learn to understand the algorithms.
3. Be sure to identify the edge cases.
4. Ask the scientist if your simplified "alternate" representation is correct
5. AND MOST IMPORTANTLY identify problems that you found; AND without sounding "accusatory" say something like "I was looking at the algorithm and noticed XYZ is it supposed to do this or is it supposed to do that?". Nothing will gain their confidence better than this bullet.

Once you start finding bugs AND have demonstrated an interest in their area of interest then the odds become much higher that at the very least they'll let you start modifying the code to make it more "professional". Frequently, they won't even feel the need to code up a prototype any longer. They'll just write something up in one of those "alternate" notations that you've taught them (without them even realizing it) and they'll have confidence that you'll know what they mean.

By all means, my first attempt would be to offer some suggestions on how the scientist could best help "communicate" better in order to help you; but it sounds like you've tried that. So the only step that you have control over is what you do. Earn their confidence and almost always the domain expert will be relieved to pass coding off to someone else and not have to worry about all the little details that go into writing code. They'd much rather be focusing on improving algorithms.

Sometimes, all you can do is offer a suggestion and leave it be after that. You won't impress your boss or a senior if you keep harping on something that they've already rejected or decided they don't want to do, even if you are 100% correct. In fact, this will damage a relationship, whether you are the suggestor or suggestee. Just focus on what YOU can do to make your job easier.

Answer 2

When he is really "someone who is not a professional programmer, never will be a professional programmer" as you say and when a large part of your work is really "taking his cobbled together code and making it production ready", it sounds like your two-man team would be more productive when he would leave the programming to you and concentrate on the managerial part of the project.

However, this assumes that you are right. We programmers always tend to disregard code written by other people as much worse than our own. This preconception is really hard to defeat and leads to us underestimating our colleagues. What you consider "cargo cult programming" might be "proven best practices" from his perspective, and what you consider "elegant application of object-oriented patterns" might be "unnecessary overengineering" for him. Hard to tell for me, because I only know your side of the story.

The disdain for other peoples code becomes stronger the more different our programming styles are. In that case that's a positive instinct, because mixing different programming styles in one project makes it very hard to maintain.

When both of you are unable to mimic the style of the other, then you could define clear responsibilities. Make one person responsible for one part of the application and the other person for the other. Define clear interfaces between both modules together, but leave the internal implementation to the one responsible. To make him more aware of bugs in his code, you could write unit-tests for him and point out when his code obviously doesn't behave according to the interface contract you specified together.

Through establishing clear code-ownership you can reach a better coexistence of your different styles. Also, when both of you are responsible for fixing the bugs in their own code, you won't have to navigate each others code often.

Answer 3

You've got to ask yourself: what is your ultimate goal here? 1. to help your boss? 2. to help the company? 3. to help yourself? And before you answer "all of the above", slow down. Your first task is to clearly define your primary objective, because the answer depends on it.

If you goal is to:

1. Help your boss? Give It Up. He doesn't appear to be asking for it. You said, "He knows his code is bad, but it does what he needs." Well then, end of discussion. Unless and until your boss is dissatisfied with the current situation, he is not going to change, and he will resent your efforts to help him. If at some point in the future he does "feel the pain" of the status quo, hopefully you will have established yourself as a trustworthy mentor and he will know where to come for help.

2. Help your company? Is the current situation threatening the bottom line? Are deadlines at risk? Is upper management increasing its heat? If not, then Give It Up. (This is essentially the point that Jimmy Hoffa made in his comment to your original post.) If, however, the current situation does in fact represent an unacceptable risk to your department/company, then a change of process is in order. In that case I would suggest that you sit down and outline a different division of labor. The key here is to explain that the time you spend refactoring your boss' code would be better spent writing new code. You say you don't have time writing it all yourself, but that's not what I'm suggesting. You need to figure out how to maximize your respective strengths. Stop thinking of him as a Mort, and think of him as a junior developer with superior domain knowledge. That is a very common working arrangement in the industry, and it would behoove you to learn how to thrive in it. For example, make sure that he knows that you know how essential his expertise is (repeat this step often), and then humbly suggest the following strategy (or something similar) as a quicker path to get his knowledge to the market: (a) break the work into "agile" sprints, (b) collaborate heavily up-front (in each sprint) defining the over-all requirements and architecture. (c) Let him go off and build the prototype to work out all the algorithmic decisions, while you build the infrastructure that you agreed upon in previous step. (d) Implement his algorithms into your structure while he builds tests to verify it. (e) Conduct your V&V together in a peer-programming environment. (e.g., "This test failed; why? algorithmic logic error or coding mistake?"; iterate here).

3. Help yourself? Be honest here. If all you are doing is complaining that you don't enjoy your job, I suggest you need to spend more time thinking about #2 above. If you don't care about the company AND you don't enjoy your job, start distributing your resume. If you DO care about your company but don't enjoy your job, then focusing on #2 should help on BOTH accounts. But in that case, it is a "win-win" only if it is clear to everyone that your passion genuinely stems from a desire to Help The Team, and not just from a self-centered frustration in your assignment.

Answer 4

I'm not sure I will add something to this discussion, but having worked in similar scenarios where an Access violation is hitting at a line with ShowMessage('Hello'); or similar, only to find out that the same line has more code, out of the screen to the right,

I believe that you have two basic options:

1. Let the code run. If the code is working and doing what it should do, unless your boss is specifically asking you to fix their code, just leave it as it is. That may also lead him to understand that your code looks nicer and leave the work to you (as also pointed by Dunk in his answer).
2. If you are very determined to make the code professional, build a library / framework that he can use. If there is a pattern on the errors / strategies that you commonly fix, you may be able to wrap those up into a few library files and give it to him as a "base library for the company", which you can also use as a common interface.