Should one programmer document another's code?

Question

Several of our lead developers have pursuaded management to assign a junior developer to document their code for them.

Their arguments are:

1. You'll have two programmers familiar with everything.
2. It's pair-programming, kinda.
3. It's more cost-effective = they will get more done.
4. It demonstrates that their code is readable and maintainable.
5. They'll be happy to answer any questions; so it's a form of mentoring.

However, the number of programmers they keep busy in order to stay current seems to increase over time.

Is this a good idea?

---

Wow! This is so not our experience!

Here are some clarifications that turn out to be important.

1. The senior developers are reflexive self-documenters. It's a core hiring question. They sometimes need to be told "leave this for the junior guy".

2. This is veiwed as a validation tool for the senior guy (and our junior guys are hired with I think pretty high bar to clear).

3. Yes, code should be single-purpose and self-documenting. If the junior guy can't comment it easily, it's feedback the seniors take seriously.

4. The juniors are expected to treat it as a refactoring exercise, and it works that way more often than you might expect. Especially catching stuff like YAGNI issues, excessive scope, etc. They get to put their seniors into the crosshairs. In fact, they originated the change. (If they really start objecting, we'll back it out. The seniors are more than willing to adjust - they understand that they more than anyone else are responsible for juniors succeeding.)

5. Don't your senior people want to explain their code?

6. We have a strong commitment to the Agile principle "everyone owns the code". We think this accelerates the process.

Finally, a personal note - when I'm trying to understand someone else's code, the first thing I want to do is re-comment it as I try to understand it. Why is commenting viewed as so onerous?

Maybe we filter out some junior applicants because we make it clear this is how we work. But it's not a turnover issue. (But it's only been 3 months.)

Answer 1

To answer the title question,

Should one programmer document another's code

I document code I'm looking at, as I gain understanding of what it's doing.

I don't care who wrote it.

Answer 2

This appears to be just a clever way to get out of mentoring. There are a couple issues that remain:

• How much time is spent in reviewing what the junior programmer wrote as documentation? This could be a significant time sink, for example, if you junior programmers mother tongue is not English.
• How is this supposed to get the junior developers experience in developing software? This form of mentoring does not address the reasoning leap from specification, to design, to implementation which is a differentiating factor between junior and higher-level developers.

Answer 3

Its not a horrible idea. Reading good code is a good way to learn, and making sure that you can write code that someone else can follow well enough to comment it is useful.

But your senior developers will still need to read and verify that comments are correct or this is just a waste of time.

And the value for the junior developer has a time limit. I would say at most 6 months before there is no real value to the junior, and even less time before you would risk losing the (now trained) junior to a more satisfying job.

So I give this a qualified maybe. If juniors and new hires have to spend a internship period commenting code - fine. But after that, they get to stop and the seniors have to go back to writing their own comments.

Answer 4

Probably not such a great idea. For a number of reasons:

• There is less incentive for leads to write proper code if there is a string of juniors that will "mop" up after them. Be that with docs or otherwise. I've never seen an incentive to reduce quality go unanswered.

• If team leads are happy to answer questions, why not just answer the questions in the pairing session? It will actually take less time because you'll be able to answer the question right there and then, without having to try and remember what you did last week.

• Pair programming is much more than just a junior developer sitting idly watching the senior. Even the most experienced programmer can learn from juniors. Even if it is just by having their long standing assumptions challenged. If you have trouble, let the junior take control of the keyboard - that usually solves it for me.

• Code should be "self documenting". Things like Javadoc, etc. have gone out of vogue in recent years because it adds little value (it is always out of date, etc.). It makes much more sense to spend the time restructuring code so that it is easy to understand.

• I don't buy the "more productive" argument. If you have 5 seniors going at full speed and 5 juniors mopping up behind them, you have only 5 devs producing code. If you have 10 devs going at 2/3 rate you have a greater overall capacity (~6 full speed devs).

Answer 5

It's better than not documenting the code. If you're going to do it, I would try to expand the role. Attempt to challenge the developers to find bugs, improve the code(dangerous, but its with the lead's guidance), write test cases and all the things that should have been done the first time around.

Set some type of incentive for the most problems a junior can find. Encourages the junior to look harder and makes the lead think a bit more before ditching their basic duties while writing code.

Answer 6

It is bad idea. Junior or not junior developers should directly impact the code. If ordinary developer can work with your code with minimal start cost, then it will be great proof that your code is maintainable. If novice developer will break something, then your unit testing needs more attention. But if you will keep creating extra artifacts, which are not part of end product, then you as a team on the way of increasing costs with no reason.

Answer 7

Whoa!! An I the only one who thinks that the time to document code is before you start pounding keys?

If your lead developers don't understand the concept of design before code (and design review), then you have some serious problems, and applying a band-aid like having a junior write up what he thinks the code does, after it is written, is not going to help.

Do you have Processes? SQA?

Answer 8

I'm not smart enough to write my own answer, so I'll quote people smarter than me:

Joel said:

Don't even think of trying to tell college CS graduates that they can come work for you, but "everyone has to do a stint in QA for a while before moving on to code". I've seen a lot of this. Programmers do not make good testers, and you'll lose a good programmer, who is a lot harder to replace.

I think the same is true, though possibly of a lesser extent, of junior developers. I don't mind documenting something I run across, from time to time, but I don't want my job to consist only of cleaning up for senior employees.

Yegge said:

A UW student I just interviewed told me that his friend did an Intel internship this summer, and hated it so much that he turned down a fairly lucrative full-time offer from them. The friend said he's convinced that an Intel employee wrote the screenplay for the movie Office Space. Not only do people there have 5 or 6 bosses to report to, which is bad enough; they actually have TPS reports, and everyone has to do them. And when they change the cover page format, a memo goes out letting everyone know.

Although that's probably one of the more surreal internship experiences I've heard about, internship horror-stories are fairly common. And it's not as if the intern doesn't tell anyone back at school. Word gets around fast. Many companies have effectively blacklisted themselves at major universities. The UW student who told me the story says that now nobody in the the CS department is interested in working at Intel. Intel is still recruiting like mad on campus, but they've effectively closed the pipeline.

In short, if you make junior developers not want to work there, they ... won't work there. If you don't have any junior developers, eventually you'll have no senior developers, and then no developers at all, if you get my drift.

The only possible explanation, then, is that you, good sir/madam, work at Google and the actual problem is that hiring top talent has become too easy, and the ulterior motive is that they want to level the playing field for smaller companies. (Nobody else would dare do something that makes it harder to hire good talent.) And in that, I wish you all the luck in the world, because my company is not Google and we would love to see more qualified candidates walk through our doors.

Answer 9

If they write clearly refactored code, they will have very few comments, if any at all.

Answer 10

An additional thought - generally, engineers don't have a thorough concept of what a peice of code is doing until they've added to it and/or tested it. Yes, it's possible through observation to get the gist of the code's purpose. But the goal of documentation should be to cover nuances and concerns that are not obvious. I don't think any developer - junior or not - is going to just look at code and write useful documentation.

Giving junior developers encouragement to enhance documentation while they are doing some other task, is a good plan, since they will inevitably catch something that seemed "obvious" to the original developer. But those reasons to document don't become obvious until you are trying to fix a bug or enhance a feature and you don't get why the code isn't working as planned.