How can I become better on explaining the code to other developers? [closed]

Question

While the question itself might sounds silly, the answer is quite important to me, as I feel that issue is negatively affecting my work performance.

A bit of the background here: I am a seasoned senior software developer in a medium size software department of non-software company. While being above average on the technical side of the things, I am much poorer on communicating and explaining things. Even when explaining something to other developers.

The most difficulties happen when I explain how a particular small piece of code works.

The funny thing is, that explaining and providing examples on how something works on a much higher level, e.g. interactions between separate modules and subsystems, is much easier for me.

To make it clearer, what I call "source code explaining skill" is a

a) ability to clearly explain the execution flow of the code - e.g. "this thingy calls that thingy, which returns that object, which is later calls method A, passing the object B to ..."

a) ability to clearly explain the problems with a current design, or, which is more important, implications of the source code change as in "if, for performance reasons, we start caching the object as a field of the class, we would have to make modification in ten different places to ensure that the cache is always in up to date state" etc

I tried to analyse why I am bad on explaining things and haven't found any explanations except maybe that I explain things in a bullet points manner, which some may find too rigid. Also when I explain things I perhaps focus too much on what I say myself and missing the questions, what people ask, but again to me it feels like these questions are often irrelevant and simply draggin the conversation away.

What could you recommend (except the obvious "practices which makes it perfect", which I don't really buy, as I think I would probably practice more of the same mistakes again and again) me to do, so I could improve the source code explaining skills.

Answer 1

One of the problems is that small pieces of code don't always explain the bigger picture. For example, when I look at unfamiliar source code in a familiar programming language I usually understand most of the individual statements. At the same time, I may struggle to understand the unfamiliar algorithm to which they contribute, what role that algorithm plays in the complete solution and why that algorithm was chosen over other alternatives. In a sense, although I understand those statements, I really don't understand them at all.

An example of this is the classic Fast Inverse Square Root function.

Some things I find useful in dealing with this:

• Explain the code in the same language the users use.
• Explain the code using standard programmer terms, e.g. Terms like "buffer", "list", "singleton" are familiar to most of us, as are common mathematical terms.
• Explain what you're doing in terms of the inputs and outputs.
• Invent words for concepts you don't have words for. Sometimes I use words like "adjuster", "chain" or "wrangler" as a short-hand for some very knotty concepts. That is, after all, how well-known terms got invented in the first place.
• Recognise that, although the few lines of code might appear simple in themselves, their role in a larger code base might be quite complex. You can't always explain them without providing a lot of background information. If that's the case, provide it.
• Give concrete examples.
• Draw diagrams.

Answer 2

The reason is simple. You think like a programmer.

Being able to explain concepts at a high-level is what we do all our lives when we want to convey ideas. However, when we program, we put ourselves in the mindset that we must understand how to do tasks in terms of many small and detailed steps. Explaining that means you have to convert "small and detailed steps" to something anyone can understand, which is no small order. If such things were easy to grasp, everyone could program. That's what makes us programmers.

However, as you've probably guessed, it's one thing to understand how to do tasks in terms of many small and detailed steps and it's quite another to explain them well.

I, too, have had some difficulty in this endeavor but I've noticed that some tricks have helped me. Assume you have a method that you've written and you must explain how it works:

• Before you start with the first line, read your method and remember what the scope is, what purpose it serves, when it is called, and why this was how you decided to do that. In short, know what it does. In this way, you can answer questions in a thorough fashion and in a way that encompasses the sense of the method (i.e. when they say "I don't understand the point of this line", you can reply, "This is what instantiates the connection to the database used throughout the program" rather than "That calls the JDBC which uses the connect string to establish a connection" which answers the question but is probably not what makes it clear).
• Explain each line in the method in terms of what each line contributes to the overall purpose of the method. Why did you put that line there? Oh right, this line calls the class responsible for taking care of input management in order to check if I needed to delegate actions in my render loop.
• Admit when your code is perhaps unclear or could be improved. If you find code that may be unclear, rewrite it in order to make it clearer. It doesn't help communication to frustrate your fellow programmer into thinking that he should be understanding what he's seeing.

In general, focus on why you put that code there rather than what it does, and you'll find that your explanations will flow more easily and they will be easier to understand.

Answer 3

I have also found myself in a similar position at times struggling with the explanation of the execution flow of code at a low level. What helped me was to pick up the programming language guide in question (Bjarne Stroustrups Programming in C++) to refresh myself as to the terminology that had inevitably faded over the years. Plus reading new language relevant articles/blogs to keep up to date with current techniques/terms.

Regarding complex design problems/implications: It is ok to say 'I can't give you an answer without doing more analysis' without giving an immediate answer. Software can get very complex and even the smartest developers can't keep all the interactions in their head all the time - plus we are all human and get things wrong or miss things.

Take time to go away and analyse code so that you can be more sure of your answer. It would certainly be better than giving an immediate, possibly misinformed and wrong answer. From a senior developers position it would be seen as wisdom and go in your favour instead of looking responsive but potentially foolish!