Think from normative documents

Software developers not only have to tap the code, but also prepare various files.

Sometimes. Writing spends time on documents, even more than spending time knocking on code.

。 So perfunctory, so that the people who read the document after the view is foggy, greatly affected the efficiency of the work.

Recently, I looked at two different software version numbers in the integrated test document, quite a feeling.

The structure of the integrated test document 1 is this:

1. Introduction

2. terminology, definitions and abbreviations

3. Integration Goals

4. Integration Tasks

4.1 Integration Tasks 1

......

Table 1

......

Figure 1

......

4.2 Integration Tasks 2

......

table 2

......

Figure 2

......

4.3 Integration Tasks 3

......

Table 3

......

Figure 3

......

......

5. Integrated tools and environmental instructions

6. Accessories

7. References

The structure of the integrated test document 2 is this:

1. Introduction

2. terminology, definitions and abbreviations

3. Integration Goals

4. Integration Tasks

4.1 Integration Tasks 1

......

table 4.1.1

......

Figure 4.1.1

......

4.2 Integration Tasks 2

......

table 4.2.1

......

Figure 4.2.1

......

4.3 Integration Tasks 3

......

table 4.3.1

......

Figure 4.3.1

......

......

5. Integrated tools and environmental instructions

6. Accessories

7. References

Everyone may have seen it. These two documents are only different in the Red font section. The other parts are the same. In the integrated test document 1, the chart number is used in the form "Figure 1, Figure 2, Figure 3, table 1, table 2, table 3". In the integrated Test document 2, the chart is numbered using the form "Figure 4.1.1, figure 4.2.1, figure 4.3.1, table 4.1.1, table 4.2.1, table 4.3.1". People may think that the difference is nothing, is a number of the scheme is different.

Do. On the surface, only the numbering scheme is different. But in the process of the software version number evolution, the difference is reflected. Why is it? Please allow me to slow down the road.

The functionality of the two software is constantly being upgraded from the very beginning of the 1.0 version to 10.0 or even 20.0.

Each time there is a version number of the upgrade, it is necessary in the integrated test document to supplement the relevant functional integration test content, mainly in the "4. Integration Task "is complete in this section. In other words, the 4th section of the content is constantly joining, perhaps from "4.1" to "4.20" and even "4.100", and these additions may be completed by different developers.

When the 4th section is sufficient, two documents show the following differences:

(1) for integrated test document 1, at the beginning of several version numbers. The number of the chart is also normal, in accordance with "Figure 1, Figure 2, Figure 3, table 1, table 2, table 3" in the Order of development. After the upgrade with multiple version numbers. The problem is out. A developer of a version number may have made the number of the chart wrong, for example, because of a busy or negligent job. It was supposed to be figure 4 and table 4, which he wrote in Figures 5 and 5, followed by the wrong chart number for the later version number.

After the development to a higher version number, the number of the chart may be this: "Figure 1, Figure 2, Figure 3, Figure 3, Figure 4, Figure 5, figure 6, figure 6, figure 6, Figure 7 ... Table 1, table 2, table 3, table 3, table 4, table 5, table 6, table 7, table 7, table 7 .....

Very obvious. This is very nonstandard and affects the reading of the document.

(2) for integrated test document 2. Even if you develop to a very high version number, there will be no problem, such as "4.10" section. The number of the chart is: "Figure 4.10.1, figure 4.10.2, figure 4.10.3 ... Table 4.10.1, table 4.10.2, table 4.10.3 ... ".

Since the number of the chart is only related to the section in which it is located, there is no need to associate it with the previous section. So it can be guaranteed to be correct.

The number of the chart is a very small problem, but we can see the different results of the different design schemes of the software. In detail, I personally think:

(1) the design of software products must take into account the future development, it can be extended. To lay a good foundation for the future version number .

The integrated Test document 2 is better in this regard, and the integrated test document 1 does not take into account the possibility of future errors in numbers, which are not designed properly.

(2) Software PRODUCT design must follow the "high cohesion, low coupling" design concept , that is, to reduce a module and other modules in the data, messages and other above the association, but should enhance the internal association of the module. The number of a section chart in the integrated test document 1 is strongly correlated with the number of the previous section chart. and the integrated Test document 2 each section of the chart number is no matter what the association. Therefore, the design on the chart number. The integrated test document 1 is much less than the integrated test document 2.

(3) the design of software products must embody the professional nature . In this regard, "figure 1, Figure 2, Figure 3, table 1, table 2, table 3" is certainly not "figure 4.1.1, figure 4.2.1, figure 4.3.1, table 4.1.1, table 4.2.1, table 4.3.1" looks professional.

So. From a professional point of view. The integrated test document 1 is also 2 worse than the integrated test document.

Writing a professional, beautiful, neat document is a basic requirement for a development project, and at the same time it is a reflection of the attitude, professionalism and ability of the project master. A qualified development project teacher should be "code" and "document" with both hands and hard hands.

(I Weibo: http://weibo.com/zhouzxi?topnav=1&wvr=5. Our chat number: 245924426, welcome attention! )

Copyright notice: This article Bo Master original articles, blogs, without consent may not be reproduced.

Think from normative documents