0 foreword

As our business grows, we often need to refactor and optimize projects.

There are two things that make this kind of refactoring a headache.

One is that there are many common functions, mixins, and other shared units for project members to share. Code structures that generate many-to-many relationships (such as one component using multiple common functions, and one common function being used by multiple components) can be a headache.

The second is that typescript is not available for a variety of reasons. You can’t document your code directly without a type hint. The consequence is that the project may have to be restructured again at a later date, and there is a great chance that the potholes will be stepped on again.

The above two situations undoubtedly greatly slow down the development efficiency:

  • For one thing, time is spent trying to understand what the code does
  • On the other hand, it’s mostly spent on repetitive communication. This is especially deadly because on the one hand, they interrupt others’ work, on the other hand, they waste their own time, sometimes waiting for others to reply, which is even more costly.

With the current limitations, this loss can only be reduced gradually by clearly annotating the function.

Ps: Use typescript if you can.

JS function annotation specification

1.1 Description Of functions

  • Format for@description descriptionStatements
  • Focus on what
  • For more complex business, write “Why” appropriately
/ * * *@description Describe the function of fn */
Copy the code

1.2 Description Parameters

  • Format for@param {paramDataType} p1 descriptionStatements
  • p1On behalf ofWill choose parameters
  • [p1]On behalf ofOptional parameters
  • [p1=xxx]On behalf ofParameters with default values
/ * * *@param {string} A Parameter Description *@param {number} [b] Parameter Description@param {boolean} [c=false] Parameter Description */
Copy the code

1.3 is described as an array parameter

  • An array must have a detailed description of each of its elements
  • Refer to section 1.2 for element description rules

Format is as follows

/** * Array arguments: *@param {array} Arr Parameter Description *@param {string} Arr [0] Parameter Description *@param {number} [arr[1]=undefined */
Copy the code

1.4 Description of the returned value

  • Format for@return {paramDataType} descriptionStatements
  • Write even if no value is returned@return {undefined}
/ * * *@return {number} Description Return value */
Copy the code

1.5 Complete Examples

The full notes are as follows

/ * * *@description Describe the role or function of fn *@param {string} A Parameter Description *@param {number} [b] Parameter Description@param {boolean} [c=false] Parameter Description * * Array parameters: *@param {array} Arr Parameter Description *@param {string} Arr [0] Parameter Description *@param {number} [arr[1]=undefined parameter Description * *@return {number} Description Return value */
function fn(a, b, c = false) {
  // code
  return 1;
}
Copy the code

example

  / * * *@description The tree component data is modified and localized only once *@param {object} Data Unmodified data * pulled from the back end@return {undefined} No return value */ is required
  cleanLeftMenuData(data) {
    / /...
  }
Copy the code

Automatically generate documentation to annotate the IDE configuration

The effect is as follows:

2.1 webstorm

Open Setting and follow the steps below

Copy in the following comments as illustrated

2.2 vscode

Vscode recommends installing the plugin document this directly

The following figure shows the configuration method