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).
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.
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.
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.
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.
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.
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.
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.
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.
It really 'depends', you need to document the specific goals of this process and then measure the outcome. It is possible this is simply a cost reduction model, that is have less paid employees do more of the required work. There could also be other values, you gave examples, and these are harder to measure (i.e. does the documenter really gaining knowledge that they can use). Bottom line there is no correct answer to these type of questions as it is pragmatic in nature, that is the consequences of this action will justify (or otherwise) its existence.
发布评论
评论（11）
可能不是一个好主意。出于多种原因：
如果有一连串的初级员工会“扫荡”潜在客户，那么他们编写正确代码的动力就会减弱。无论是文档还是其他方式。我从来没有见过降低质量的动机得不到回应。
如果团队领导很乐意回答问题，为什么不在结对会议中回答问题呢？实际上，这会花费更少的时间，因为您可以立即回答问题，而不必尝试记住上周做了什么。
结对编程不仅仅是初级开发人员无所事事地看着高级开发人员。即使是最有经验的程序员也可以向初级程序员学习。即使这只是他们长期以来的假设受到挑战。如果你遇到麻烦，让初级开发人员控制键盘 - 这通常可以为我解决问题。
代码应该是“自记录的”。像 Javadoc 之类的东西近年来已经过时了，因为它几乎没有增加任何价值（它总是过时的，等等）。花时间重构代码以使其易于理解更有意义。
我不相信“更有成效”的论点。如果你有 5 个前辈全速前进，还有 5 个后辈在他们后面扫荡，那么你就只有 5 个开发人员来编写代码。如果您有 10 个开发人员以 2/3 的速率运行，那么您的总体容量就会更大（约 6 个全速开发人员）。
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).
这并不是一个可怕的想法。阅读好的代码是一种很好的学习方式，并且确保您编写的代码其他人可以很好地遵循并对其进行评论，这很有用。
但是您的高级开发人员仍然需要阅读并验证注释是否正确，否则这只是浪费时间。
对于初级开发人员来说，价值是有时间限制的。我想说，最多 6 个月，对于初级员工来说没有真正的价值，甚至更短的时间，你就会冒着失去（现已接受培训的）初级员工去从事更令人满意的工作的风险。
所以我给这一个合格的也许。如果初级员工和新员工必须花一段实习时间来评论代码 - 很好。但在那之后，他们就停下来，前辈们必须回去写自己的评论。
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.
为了回答标题问题，
我会记录我正在查看的代码，因为我了解了它在做什么。
我不在乎是谁写的。
To answer the title question,
I document code I'm looking at, as I gain understanding of what it's doing.
I don't care who wrote it.
哇！！我是唯一一个认为记录代码的时间是在你开始敲击按键之前的人吗？
如果您的首席开发人员在编码（和设计审查）之前不理解设计的概念，那么您就会遇到一些严重问题，并且可以使用创可贴，例如让初级开发人员写下他认为的内容代码在编写之后并没有什么帮助。
你有流程吗？质量保证局？
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?
另外一个想法 - 一般来说，工程师在添加一段代码和/或对其进行测试之前，对一段代码的作用没有一个完整的概念。是的，通过观察可以了解代码目的的要点。但文档的目标应该是涵盖不明显的细微差别和问题。我认为任何开发人员（无论初级与否）都会只查看代码并编写有用的文档。
鼓励初级开发人员在执行其他任务时增强文档是一个很好的计划，因为他们不可避免地会发现一些对原始开发人员来说似乎“显而易见”的东西。但是，直到您尝试修复错误或增强功能并且不明白代码为何无法按计划运行时，记录这些原因才变得显而易见。
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.
这比不记录代码要好。如果你要这么做，我会尽力扩大这个角色。尝试挑战开发人员发现错误，改进代码（危险，但在领导的指导下），编写测试用例以及所有应该在第一次完成的事情。
针对初级员工能发现的最多问题设置某种类型的激励措施。鼓励初级人员在编写代码时放弃基本职责之前更加努力地观察并让领导者多思考。
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.
这是个坏主意。初级或非初级开发人员应该直接影响代码。如果普通开发人员可以以最小的启动成本使用您的代码，那么这将很好地证明您的代码是可维护的。如果新手开发人员会破坏某些东西，那么您的单元测试需要更多关注。但是，如果您继续创建不属于最终产品一部分的额外工件，那么您作为一个团队就会无缘无故地增加成本。
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.
我不够聪明，无法写出自己的答案，所以我会引用比我聪明的人：
Joel 说：
我认为对于初级开发人员来说也是如此，尽管程度可能较小。我不介意记录我时不时遇到的事情，但我不希望我的工作只是为高级员工打扫卫生。
Yegge 说：
简而言之，如果你让初级开发人员不想在那里工作，他们……就不会在那里工作。如果你没有初级开发人员，最终你将没有高级开发人员，然后根本就没有开发人员，如果你明白我的意思的话。
那么，唯一可能的解释是，您，好的先生/女士，在 Google 工作，而实际问题是聘用顶尖人才变得太容易了，别有用心的动机是他们想要调平小公司的竞争环境。 （没有人敢做一些让招聘优秀人才变得更加困难的事情。）在此，我祝你们一切顺利，因为我的公司不是谷歌，我们希望看到更多合格的候选人走进我们的大门。
I'm not smart enough to write my own answer, so I'll quote people smarter than me:
Joel said:
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:
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.
如果他们编写清晰的重构代码，那么他们的评论（如果有的话）也很少。
If they write clearly refactored code, they will have very few comments, if any at all.
这似乎是摆脱指导的聪明方法。仍然存在一些问题：
This appears to be just a clever way to get out of mentoring. There are a couple issues that remain:
这确实“取决于”，您需要记录此过程的具体目标，然后衡量结果。这可能只是一种降低成本的模式，即让工资较低的员工做更多所需的工作。还可能有其他值，您给出了示例，并且这些值更难以衡量（即文档编制者是否真正获得了他们可以使用的知识）。底线是，这类问题没有正确的答案，因为它本质上是务实的，即该行动的后果将证明（或以其他方式）其存在的合理性。
It really 'depends', you need to document the specific goals of this process and then measure the outcome. It is possible this is simply a cost reduction model, that is have less paid employees do more of the required work. There could also be other values, you gave examples, and these are harder to measure (i.e. does the documenter really gaining knowledge that they can use). Bottom line there is no correct answer to these type of questions as it is pragmatic in nature, that is the consequences of this action will justify (or otherwise) its existence.