This is the fifth day of my participation in the First Challenge 2022.

preface

I’m sure many new programmers don’t know why they write comments, what they do, and why they waste time and energy. There are plenty of gurus who will tell you that good code is well explained and doesn’t require comments. Today, let’s talk about whether or not we should write comments, and how we should write about it.

Annotation syntax

First, review how the basic comments are written in the three main pieces of the front end.

HTML comments

// HTML comment <! -- but line comments --> <! @description: add annotation doc (module description) @author: Hecate (module author) -->Copy the code

CSS comment

* @description: * @author: Hecate. Zhu * @update: hecate.zhu(2021-03-11 15:24) * */ .cass{ display: inline; } /* module comment */ / module: Zhu */ /* this is a short comment */ * * this is a short comment 1 * this is a short comment Comment 2 */ * * TODO: XXX by Hecate 2021-03-11 15:27*/ * BUGFIX: XXX by Hecate 2021-03-11 15:27*/Copy the code

Js:

// js annotation // single line annotation: /* multi-line annotation */ /* * paragraph annotation module annotation method annotation: * here is a single line annotation * here is a multi-line annotation */Copy the code

How and Why

Good code should be readable, but code can describe how, but it can’t explain why. What should a comment say?

Obviously, the primary function of comments is to explain why this code is written, that is, why it needs to be explained. Explain the immediate reasons for this module, what this module does, what it does, and if your input and output parameters are not clear, explain the types and meanings of the parameters in detail.

Second, your comments should make special references to obscure parts of your code, other syntax and modules that depend on it, and if your code has specific usage scenarios, such as those that rely on versions higher than JQ1.21.

Eg1: The following comments indicate the function of the method, the applicable scenarios, the types, fields, and meanings of the parameters. * @param {number} productId commodity ID * @memberof orderController */ eg2: Mainly describes the function of the method, use suggestions, application scenarios; // Type enumeration: 'Mobile Safari'; // type enumeration: 'Mobile Safari'; 'WeChat' ; 'App' ; 'QQ' ; 'ali' ; Eg4: CSS module annotation, compared to CSS annotation is much simpler, generally only need to module annotation or hack or special part of the brief description can; / /. M -panel{background:# FFF; padding-left:.30rem; margin-bottom:.20rem; } EG5: HTML annotations are generally targeted at the page structure layer or function module layer. It is only recommended to focus on special parts and large separate modules. <! - m - the title head module -- -- > < div: class = "[' m - the title '(OS = =' iOS '&& uatype = =' App ')? 'the iOS' : ']" > < / div >Copy the code

Other Rules for writing comments (Scenario)

  • Clarify some common people can not recognize single things, such as long single regular verification, some complex design principles.
In addition to variable naming conventions, it is also suggested to describe the idea of true drop matching, such as: Validation of 13, 14, 15, 17, 18, 19 at the beginning of 11 phone number let phoneReg = / ^ ([0-9] (13) | (14 [0-9]) | (15) ([0-9]) | (18 [0-9]) | (17 [0-9]) | 190) \ d {8} $/Copy the code
  • Book sheet chapter notes, in addition to individual methods, for the episodic, with a coherent single several methods also want to write chapter notes.
// use xx1,xx2,xx3 methods to implement login logicCopy the code
  • A guide to keeping logic flowing when writing code
Check whether you need to log in. // If you need to log in, verify the token. If the token is valid, continue the operation or invalidCopy the code
  • It can be refactored, and technical debt under development can be annotated to facilitate subsequent single refactoring or removal
// this isn't my best work, we had to get it in by the deadline
Copy the code
  • As an important reference for teaching or maintenance or later iterative development
Par {display:table}.par.sub {display:table-cell; vertical-align:middle; }Copy the code
  • Complex logic
  • There are certain problems, to be patched

conclusion

If you want to keep and continue to use your valuable code, it is necessary to write comments for your team’s skill level and the purpose of the code.