Based on what I have taught and learned so far I tried to summarize what I was happy (or should have done) with the standardization of the team.
I wrote something general about what rules are needed to put the team together. I hope that those who will be leaders and members will think that this can be used. Also, if you have something like "I was doing something like this", I would love to hear from you.
Design documents are likely to be exposed to the outside eye, so make an effort to eliminate blurring in terms of appearance. Also, if you create a template and try to create it based on it, If you feel that the template doesn't match your project, you should also review it regularly.
The details are as follows.
If the contents are not unified between the design documents, it will be directly linked to the difficulty of reading.
However, if the rules tend to be fixed, there will be processing that cannot be expressed in the current design document. A certain degree of versatility is required.
As a solution, it is effective to format the repetitive processing. In general, format the following interface-related parts and processes. ・ DB access ・ File reading / writing ・ API call ·loop ・ Branch
In addition, the following is a list of contents that should be unified, which is often forgotten. It's fine, but I feel that the seeds of conflict within the team come from this place. .. ..
| Contents | Example |
|---|---|
| Description of the same meaning | ・ Register in DB ・ Insert 〇〇 on the table ・ Register 〇〇 in the table ⇒I think the bottom is the best in terms of writing as concretely as possible and closer to the design document. |
| General-purpose words | DAO and Util class methods"API"Called uniformly ⇒Because there is a possibility of recognition discrepancy, let's unify if there is a problem. |
| Class name / method name | Mixed Japanese and English names ex) Japanese name:Member information registration English name:registerCustomerInfo ⇒ If this is not unified, refactoring will not be possible. .. .. |
Consider the characteristics of the language you are using, and think about component division (in which unit the class is created). For example, Java is based on object orientation.
The basic idea of object orientation is encapsulation, inheritance, and polymorphism. By comparing it to a thing (class) in the real world, we will imagine what kind of information it has (property) and what kind of behavior (method) it will do, and divide it.
However, the programs you actually create are all that cannot be compared to real-world objects. For example, if most of the processing is to process the received data and register it in the DB, and then only variations such as external cooperation are added. I think I'm desperate, "Isn't that really the case?"
Therefore, let's focus on the data once. The data is stored in a table and retrieved when needed. The table is normalized and has a logical and physical design.
** It is best to create a class around this logically divided table. ** **
The point is to think of it as a window (thing) that specializes in handling that data. This example does not apply in all cases, I think that proper function placement enables active method placement.
Indentation is the skeleton of the specification, but I think it's okay to some extent.
However, if the indentation is deeper than the following indentation example, it is recommended to review the processing because of readability problems (or other problems). Also, by indenting branches and loops, It will be consistent with the program.
Indentation example
1.
___1).
______(1).
_________➀.
____________a.
_______________a).
__________________(a).
(topic) When a new employee arrives, instruct them to write the process from the major item number, By reviewing each item number, you can make the titles uniform in the same item number as the rework.
TODO Let's decide where to leave the TODO, If this is not decided first, members may forget to leave TODO. Also, if it is possible to summarize the contents of the TODO, it is also a good idea to number and manage the code for the TODO. This has the advantage of being able to mechanically approach TODO of the same cause.
** Decipher the code I wrote for decades ... **
I definitely don't remember this w If you can't remember, let's create a mechanism that you don't have to remember!
Read readable codes and design patterns, Create rules that force smart implementations for each language (highly readable, resistant to change, and the behavior of each function can be inferred).
The following is a typical example.
I remember being pointed out until I heard an octopus saying, "Name is important." .. .. Let's make the basic contents into rules!
** Rather than falling apart without deciding, if you unify it, you can do something with refactoring! ** **
When giving method names, class names, and variable names, the contents that you will probably use are defined as conventions.
ex) Register: register Update: update Registration: insert
Don't have hyphens or not.
ex) Constant: Snake case (and all uppercase) ⇒ MAX_RANGE Variable name / method name / class name: camel case ⇒ getUserInfo URL / File name: Spinal case ⇒ user-info
I think that Japanese people may adopt the Hepburn system to avoid typographical errors and misuse. I think it doesn't matter which one, but it's embarrassing to find a Hepburn romanization.
There are WEB tools, so let's make effective use of them.
** Once written, don't write anymore (make it a function!) ** Maybe this is the content.
Development editors such as eclipse have the ability to function (refactor). You may want to investigate the functionality of the tool you are using to some extent.
Ask them to consider whether the process is method-specific or class-specific (or application-specific). By creating the Util class and the constant class first, I think you can approach the slack.
In addition, even if it is a function unique to that process, you may instruct it to function at the indent large / medium item number level of the detailed design. (Reviewing the spaghetti code is very difficult.)
I would like to stick the indent large and medium item level of the detailed design entirely.
However, what is important is the relevance to the detailed design. Point out nonsensical comments during the review.
The phase is so important that there is also the word test first. Also, if the viewpoint fluctuates, it becomes difficult to review the comprehensiveness.
fundamentally, ** White box for the code part I wrote ** ** Black box for components to call ** It will be based on thinking about UT and IT according to the phase.
If there is spare capacity, create test data covering all data variations for each table, It is also an effective means to have a business expert create the data.
Let's make a self-check sheet. Simply listing the rules this time on the check sheet will reduce a considerable number of rework.
** The content of the review indication is almost the same. ** ** Also, the mistakes made by someone will be made by someone else. Be sure to share the whole thing and take some measures (tools, etc.).
Even if the indication exists only in a specific process, if the rework is large, you may consider writing it on the self-check sheet.
Before you get into the real work, get rid of tasks that you forget or just put off.
** While searching for where it was, I didn't understand why I wanted the material. .. .. ** **
Didn't that happen? (I was w) Make a collection of links to your framework and library documentation.
It's also a good idea to color-code the minimum content you should read for newcomers. (I'm sure it will be useful later.)
Let's identify in MECE and chronological order, and create folders that will be used in the future in advance. (It's hard to make later.)
.
├─00_Common
│ ├─
│ │
│ └─
├─01_Detailed design
├─02_Implementation
├─03_UT
└─04_IT
** I think it's the most important thing I've introduced so far. ** **
If you have a nice tool, use it for a fee! As a reminder, do not create multiple information sharing tools. Even if the source of information is email, think of a mechanism that allows centralized management.
We also recommend that you give your shared content a descriptive title.
In order for members to reach their full potential, they need to show clear goals and discretion to perform the task. Therefore, creating rules to determine the discretion of a task is a very important process.
Also, the mistakes made by the members are due to the mechanism in the first place. The leader who did not make such a rule is responsible.
That's why the rules are insanely important.
It sounds very difficult to formulate, but the idea is simple. Make sure that the rules give you: ** ・ Be simple ** ** ・ Being quantitative **
If you keep this in mind, you won't be far off the road!
Recommended Posts