How to better speak code to colleagues?

Our technical team has two habits: first, the programmer wrote a new more important system, or introduced a third-party framework or library, the main routines requires the programmer to do a PPT, in the conference room to all the program and QC to do a team to share; second, the programmer wrote a new system, Or do a relatively large or more important changes, to know the relevant QC, and QC called to the computer, a pair of related code to the QC to tell it again.

I think that doing PowerPoint team sharing can play two important roles: one is to allow the team members to exchange frequently, to avoid each person only to understand the small piece of content that he is responsible for, the long-term maintenance of this habit, can improve the cohesion of the technical team, also can help the technical team to remain agile. Second, the sharing of PPT can also be used as a development document, left in the repository for future review.

but at the meeting to tell you the code, often encounter a problem: the code is too thin too deep, we are easy to understand, because most people have not specifically focused on the business I do. Once the audience does not understand, it is easy to wander, energy is not very good and sleepy, and even sleep is possible. So I think, at least for our team at this stage, it is not appropriate for the group to do the code review directly at the meeting, it will be a waste of time.

So how do you make this kind of sharing truly worth it? I think the key is to grasp the "exchange" for the purpose of grasping the good degree. The purpose of PPT sharing is to let everyone know what my business process and data structure look like, what the code framework is, and what the main responsibilities of each module are, what are the important interfaces; If a colleague's work involves my system in the future, he Before the start of work can think of my system is related, I share the purpose is basically achieved. If he needs to know more about my system, when he gets back my ppt, can quickly find the code of the system, and read the PPT and the code in the process can think of something I say, speed up his understanding of the code speed, then my sharing purpose is perfect . ppt Sharing purpose is not to let everyone on my code to check the bug, not to let everyone when small duck (see Small yellow Duck debugging method), because everyone's time is very valuable.

So I intend to use the following ideas to do ppt sharing:

1, first estimate good sharing time, start to tell yourself time is limited, to focus, do not detail. The average continuous focus time of a person is said to be only more than 40 minutes, about a class time. Under our usual tense development rhythm, you may be more likely to get tired, so time should be shorter. Better control in less than 20 minutes, not enough for half an hour, not super.

As long as the first set a good amount of time, the whole PPT to share the tone of the basic set up, the back to do PPT easy to grasp the focus, the PPT will not be a very leisurely beginning, and then more leisurely (let listeners want to sleep), or in turn found that time is not enough. If you feel that the system is too large, then the content is compressed, the size of the more coarse point. Any content in any system can be expressed in any granularity to others, which is an important experience for me to do academic report in the years of graduate school.

2, the beginning of PPT, first tell everyone I do this piece of things is to solve what problem, realize what function. For example, my recent random name has been moved to the server to ensure that after the player has applied for a random name, it will be possible to create a new character with the name, without the "name occupied" situation. In addition, the purpose of a new game system may be better to do a little elaboration from a planning point of view (by the way to help close the distance between the program and planning).

3, if the system involves inter-server, inter-process interaction and architecture, then give the involved server architecture diagram, so let everyone know where I am responsible for the system in the architecture. For example, I do log on the PPT share, will tell you through the architecture diagram, the players see each game suit in the technology contains what the process of the database, game clothing and game clothing between how to divide, the region and the region between the division, the game suit and the interaction between the game suit is through which process. This step is because my work often involves framing and interacting with the process, such as the management and monitoring of the cluster in the old club, the patch mechanism, and the now responsible login, cross-service and GM tools . Most systems should not involve this step.

4. Then, the main business process is elaborated. You can use a flowchart, or you can use a time series diagram. I tend to use time series diagrams because it makes it easier to show interactions between processes and processes, between classes and classes, and between modules and modules. Note that as long as the main process, the key steps can be, not every detail of each point to speak out. Exception handling and protection logic in the process is ignored. If you have more understanding of colleagues asked about the problem of exception handling, you can one or two simple introduction to the treatment plan, and told him that the PPT will be dedicated. If the process sequence is complex, a simplified sequence diagram can be produced first, followed by a more detailed version. The detailed version of the timing diagram does not have to be said on the spot (depending on the degree of proficiency and interest of the colleague), stay in the PPT for later review. In addition, in the process of elaborating the process, incidentally introduces each related class, module responsibility. Important protocols and interfaces are also given in this step.

5, introduce the main data structure. I'm getting the feeling that there are very few sophisticated algorithms in real product development that we need to worry about, but the data structures are much more important. What data structures are used to a large extent determines what your code looks like and how it performs. For other colleagues, they know the data structure of my system, and the system will be more in my heart. In particular, we do the game, basically is to manipulate the player's data, to understand clearly what the player with what kind of data is very important. The description of the data structure, can draw as far as possible to draw, and then use the development language to write examples of data structures, such as we use LUA, I may describe the players have learned the professional skills:

Job_skills_ =

{

[ID of skill 1] = level of skill 1,

[ID of skill 2] = level of skill 2,

...

}

Glance.

6, if the system involves database storage, then the database table structure, and from the database to query a few actual records, affixed to the PPT, if the record is too long on-site demonstration. Do not paste the SQL statement used to create the table directly in the PPT. I have tried, even if there is only one field in the table, when I see a series of letters on the PPT, my heart will be a little resistance to boredom. It is much clearer to use tables to describe the structure of database tables, which should be done in university database courses.

7, PPT Finally, the development process encountered some of the points prone to bugs, as well as exception handling and protection logic. You can then post some code appropriately. But don't put it all up. Each page PPT tells a point, the related function is pasted up; the function name and file name are reserved for later search; The code that is irrelevant to the exception that is on this page is deleted and replaced with an ellipsis; the key one or two sentences are marked with a highlighted color. everyone in front of the process and data structures have been understood, the details of the problem here is easier to understand, but also to listen to. In this step, more colleagues will ask a deeper question, then you can open the original code for everyone to see.

So the PPT is finished here. Throughout the process, the original code is only shown until the last step, unless requested by a colleague. Remember that one time the main process with a single-use PPT version of the practice, the whole process is not shown what code, but later when my work involves this part, I can recall what he said, and through his PPT to quickly understand the relevant code, should say that the purpose of the share is perfect to achieve.

To the QC a pair of code to talk about the idea is also roughly the same. The difference is: to the QC code will not be prepared in advance PPT, so involved in the structure, the flow of things best on paper. Do not start directly to the code to tell the process, from this function to jump to another function, jump to jump, so that although you speak very much, but the QC look at the screen flipping over the code will also faint-this is my personal experience, I have heard people say the code. Although the QC can serve as part of the role of small yellow duck, but after all, people's time is also valuable, so still let others understand master as well. In addition, because this is a pair of a talk, and QC on what I do is generally more familiar with, so some places can be said relatively thin. But it's best to put it in the end, either verbally or on paper, and then go through the process more specifically over the code.

How do I better tell my colleagues about code?