Annotation specification for Database Programming

1.6 annotation Specification
Annotation SpecificationIt is an important indicator for determining the advantages and disadvantages and maturity of a developer. A good R & D engineer must be well-thought-out and then be able to write comments. The writing of comments reflects the whole process and steps of a person's thinking about the problem. Then again, even if the code is poorly written, as long as the annotations are well written, they will at least give people a good feeling. At the same time, they will benefit future generations, right? Haha.

Rule 1.6. 1

Generally, the valid comments of the source program must be around 30%.

Note: The principle of annotation is to help you understand the program. It is added to the place where the annotation is added. The annotation language must be accurate, easy to understand, concise, and refined.

Rule 1.6. 2

Unified File Header comments.

It mainly describes related processes and functions, revision records, and input and output parameters.

Any modifications to stored procedures and functions must be annotated with the author, date, reason, and other revisions.

/*************************************** ********************

Name: sp_xxx

Function Description:

Revision history:

Version Number editing time modifier modify description

1.0.0 2010-01-01 John 1. Create this stored procedure

1.0.1 2010-02-01 Sandy 2. Add input parameters

Description of input and output parameters:

Iparameter1 IN VARCHAR2 (20) input parameter 1

Iparameter2 IN VARCHAR2 (20) input parameter 2

Iparameter1 OUT VARCHAR2 (20) input parameter 1

Iparameter2 OUT VARCHAR2 (20) input parameter 2

Return Value Description: (mainly for functions)

0-Success

1-normal fail

**************************************** *******************/

Rule 1.6. 3

All variable definitions need to be annotated to describe the usage and meaning of the variable.

Rule 1.6. 4

The content of the comment must be clear, clear, and accurate, so as to prevent the ambiguity of the comment.

Provides useful and additional information by commenting on the functions and intentions of the Code.

Avoid inserting comments in the middle of a line of code or expression.

Try to use "--" for comments; Use "--" for comments at the end of a line "--".

Rule 1.6. 5

Comments must be written to the program branch.

Note: These statements are often the key to a program to implement a specific function. For maintenance personnel, good comments help to better understand the program, sometimes better than reading the design documentation.

Add a comment to the right of the end line of the block to indicate the end of the block.

Rule 1.6

The comment should be similar to the code described in it. The comment on the code should be placed above it or on the right side (the comment on a single statement), and should not be placed below.

The comment is the same as the description.

The code above should be separated by blank lines.

1.6. 7 is recommended.

Notes written in Chinese

On one occasion, my colleague wrote a 900-row stored procedure, which defined more than a dozen cursors for traversal. This stored procedure lacked annotations and it would take one day and one night to execute one operation, it has reached an intolerable level.

Due to the lack of annotations, I spent a whole day analyzing the stored procedure, and then spent half a day writing and debugging.

In fact, it is very simple to define. I have defined some corresponding temporary tables, replaced the cursor traversal with the SQL set operation, and split the entire large transaction into several small transactions, only a part of the code has been modified, and the result execution time has changed to 3 minutes.

Of course, the cursor is not untouchable. Since it exists, there is a reason for its existence.