No comments, no documentation. Hold on

I’ll show you a sword flower

Common problems in front-end team project development:

How many projects start out as big plans, only to end up as garbage mountains over time?

1. Component layer

In a project, there are several components developed by different people that have almost the same function.

This is especially true for large projects with a certain number of components

In the development of the project, the first page will be split from the UI level into several components with smaller granularity, and finally assembled into a page. Those of you who have worked on mobile projects will feel it even more. PC pages are relatively specific, so the need for split components is not as high.

When multiple developers collaborate on a project, requirements are segmented not by pages but by component modules. Reusable components with high similarity are categorized and assigned tasks.

In this process, there will be the following situation: front-end A and front-end B students need to develop some components developed by front-end C students, and can be directly referenced. Most of this communication relies on verbal communication between developers, and this unstable communication may cause front-end A and front-end B to write the component again.

and

Some projects are two, three, four years in progress, not to mention the level of coordination between the development, the developer alone can probably change rounds.

When a new developer gets the project code, if the previous documentation is not perfect, he can only look at the specific page first, then look at the corresponding code reference components, and analyze which component corresponds to which module one by one. This is a headache, a hassle, and a lot of effort, and in general, most developers would rather write one themselves. Over time, there will be multiple different components with the same function. It’s even worse when there’s another round of developers.

To see that happen in the next development, it’s really torture.

2. Project architecture

There are two main types of front-end architecture

1. Use mature scaffolding projects, such as ADnt Design Pro, Element-Admin, etc. 2. Build the project by yourself, and further encapsulate each module according to your own understanding (those who rely solely on vUE or React scaffolding to generate the project shelf, hands can be put down).

Here do not speak first between their respective advantages and disadvantages, there is a very important difference is that the first will be a specification and detailed documentation of the introduction And the second is usually depends on the development of the work handover between oral interpretation (lucky words, may be someone to tell you (￣ ￣ _)), or to develop its slowly see code to understand.

It is more dangerous to have actions that are not consistent with the original architectural design than to have different code styles. For example, at the beginning of the architecture design of the project, we planned to manage routing in a modular way according to business classification. However, the new colleague did not know that you just divided several folders, so he handled the demand that routing was placed in one module regardless of business type. The colleague in the back sees two rules, how should he choose? The future direction of the project architecture is unknown. Formal and detailed documentation is important; don’t rely on developers’ ability to understand the code for the direction of the project architecture.

3. Code

It’s a cliche to say that there are two things programmers hate the most: writing their own comments and not having others write them.

Friendly code comments can be a great aid in later code maintenance, making it easier for others to find key code and avoid reading irrelevant code logic.

“Please don’t insult my intelligence with comments, but don’t test my eyesight with code.”

// Declare a variable
const size = 10
Copy the code

For example, above this kind of notes need not…. Most of the time, you just need to comment on the key code

/** * Determine whether the user is an alien *@param User {Object} User information *@return { Bollean } True: aliens,false: not aliens */
function isAlien(user){I am lots and lots of abstract code....// Some key comments
}
Copy the code

3. Problematic front-end team documentation specification landing

From my own experience so far, there are several companies that have a documented front end team, but none of them work very well. It basically relies on wiki, Tencent documents and other third-party systems for unified management. Documents generated by all departments of the company are classified and managed here. Not to mention the legibility of the documents themselves, the clutter of the document “repository” is enough to make some people not bother to open the system and look through the documents related to the project.

Documentation is too detached from the code and, for the concept of component management, it is questionable whether documentation that is detached from the project code meets the needs of developers. To be specific, if an Element-UI document was made up of images, screenshots and text, without component interactivity, the user base would be reduced by 30%.

Solution: Local document system

On two levels:

1. Documents related to project architecture: such as directory introduction, permission verification, routing mode, build and release, environment variables, development specifications, FAQs, etc. Component aspects: examples of packaged components in a project are compared to the Elemental-UI official documentation

Imagine a project that has two pages, an elemental-admin official website document that describes the architectural issues of the project and an Elemental-UI official website document that describes the components of the project (which can have component interaction). And all can be edited online.

Results:

This is a background management system. In the left menu, in addition to the page navigation of product requirements, there is also”Project guide“This plate. The project guide is separate fromArchitecture design.The directory structure.Common components. And other dimensions to describe the document. This document is jointly maintained by the project’s developers

The pages in the project guide will only exist in local development mode for developers to read. None of the relevant code in the project guide page will exist in the build package. And the page entry will only exist in local development mode. The content of the project guide follows the Git branch, and the project guide can vary from branch to branch. Documents can be edited online, divided into preview area and edit area, and real components can be introduced to produce corresponding interactive effects

1. How much does it cost to write a document page from zero?

The document in Figure 2 doesn’t even take a minute to complete.

2. Is it a big deal to integrate such a document system into the project?

The answer is yes, I have tried this framework on four or five projects and the results are quite remarkable, especially in terms of the communication cost of the New Colleague interface project. And the development of common components in the project will be smoother.

3. How much did it cost to develop this documentation system in the project?

It does take a certain amount of time. I spent nearly a week from design to landing, and I spent a lot of time thinking about the design.

4. Should every project integrate and develop another document system?

From the perspective of architecture, if a company wants to accumulate technology, it must have its own technical architecture. It is impossible for every project to be rebuilt or to adopt the two-split template project in the market. This document system is suitable for the development of their own company template project scenario, once and for all, the following projects are using this template project for two, and continue to collect opinions and maintenance.

5. Specific implementation ideas and technology stacks involved

First of all, we need to confirm the premise that the documentation system is for developers to see, and can not affect the normal product page. Even in the package built by build, we can not see anything in the documentation system, and can not affect the package code volume after build because of the code of the documentation system. Check the details

1. You need to wrap a Markdown editor and persist the interface when CTRL + S is saved 2. The interface is nodeJS and the backend framework is optional. 3. The NodeJS service is integrated with the local project (those who have written NUXT should understand better). The following figure

4. Modify the original project startup command to start vue project and NodeJS service at the same time (automatic port allocation is made, and multiple projects can be opened at the same time)package.json

"scripts": {
    "serve": "concurrently \"node src/server/index.js\" \"vue-cli-service serve\""
  },
Copy the code

6. Define. Vue files and introduce markdown editor to register routes. 7. Optimize step 6. The content in Step 6 can be automated, one-click registration and so on. 8. As for the route entry, it can be encapsulated as navigation according to the design of the project. I made a component that automatically generates menus according to the route.

6. Why is there no implementation tutorial or code

If you want to build a good project architecture by yourself, you need to be able to design architecture and have a good code base. It’s not a problem to implement a better version based on the ideas I’ve provided. If I post a detailed code tutorial, even if most people can implement it, but do not have the corresponding architectural capabilities, it will be difficult to maintain later, that is not a good idea. Another reason is that at present, I think it is not perfect enough. At least, there is room for improvement in my opinion. However, the document system in this architecture has already begun to exert considerable power in my company. After this architecture is more mature, or after seeing the comments in the comments section, we will consider putting it on Githup for open source (it is only a demo of the document system, and has nothing to do with the company project).

7. Can this architecture alone solve all problems?

Of course this is not possible, any good tool needs to be used properly, and if it can be combined with the implementation of the front-end team’s own specifications, it will be a great addition. But if it’s just one person trying to implement the front-end team specification, and you’re not lader, it’s not impossible, it’s very difficult!