Let you know software development in advance (26): Database script comments

Part 1 notes of database scripts in Database SQL 1. Overview notes play an important role in programming languages. Beautiful and proper comments not only help developers understand programs, but also improve programming efficiency (and thus improve service efficiency ). However, it may be because of busy work that many developers do not pay attention to writing comments,

Part 1 notes of database scripts in Database SQL 1. Overview notes play an important role in programming languages. Beautiful and proper comments not only help developers understand programs, but also improve programming efficiency (and thus improve service efficiency ). However, it may be because of busy work that many developers do not pay attention to writing comments,

Part 1 Database SQL language

Database script comments

1. Overview

Annotations play an important role in programming languages. Beautiful and proper comments not only help developers understand programs, but also improve programming efficiency (and thus improve service efficiency ).

However, it may be because of busy work that many developers do not pay attention to the writing of comments, which also makes it difficult for other developers to understand the program during project handover, I don't even know what the program is going to do. Therefore, writing good comments is a basic requirement for a developer and everyone must pay attention to it.

We recommend that you use English for script comments, which can be international, professional, and normative.

2. Comment on the header of the database script file

Many script files do not have header comments, which are not considered important. However, the author believes that this part of content must be added to facilitate tracking of version information in the future.

In the comments in the file header, you can use the following styles to include copyright, database type, creation date, author, modification record, and other information:

--*************************************** ******************************

-- Copy right (C) 2014, company name.

-- DB Type: XXX

-- Content: XXX

-- Created: YYYY. MM. DD

-- Modify1: The name of the author

-- Date1: YYYY. MM. DD

-- Version1: The original version of the product

-- Modify2: The name of who modified the file

-- Date2: YYYY. MM. DD

-- Version2: The updated version of the product

--*************************************** *******************************

3. Comment on the summary of database script files

After commenting on the header, do not create tables and stored procedures immediately. Instead, you should have a summary. For a table creation script, the summary is the name and purpose of the table included in the file. For a script for creating a stored procedure, summary is the name and purpose of the stored procedure included in the file. This abstract can serve as an index to help developers understand the main content of script files.

The following styles can be used to annotate abstract information:

-- ********** XXX (Version) DataBase Table Creating *********

-- * 1 table1: description1

-- * 2 table2: description2

-- * 3 table3: description3

......

--*************************************** ************

4. Notes at the beginning of a table or stored procedure

You can add notes at the beginning of a table or stored procedure to facilitate locating and viewing. You can use the following styles:

-- XXX (The name of the table or procedure, and what it is used)

The definition of the table or procedure

5. comment after each field in the table

After defining fields in a table, you need to comment on each field to help developers understand its role and avoid speculation and misunderstanding. In this way, it will be easy to use.

Table definitions and field annotations can adopt the following styles:

Create table tb_XXX

(

AAA int not null, -- description1

BBB varchar (256) not null, -- description2

CCC int default (0) null, -- description3

DDD varchar (256) default (''') null, -- description4

......

)

6. Notes for Stored Procedures

Generally, stored procedures include a large number of SQL statements, so annotations are complicated. Even so, there must be comments in some key statements, Otherwise other developers will have a hard time reading them.

You can write and annotate stored procedures in the following format (taking the syntax in the Sybase Database as an example ):

Create procedure pr_XXX

@ AAA varchar (30), -- description1

@ BBB int, -- description2

......

As

Begin

Declare

@ CCC int, -- description3

@ DDD varchar (100), -- description4

......

......

-- YYY (name) add YYYYMMDD for ZZZ begin

......

-- YYY (name) add YYYYMMDD for ZZZ end

......

Statement1 -- YYY add YYYYMMDD description5

......

Statement2 -- YYY modify YYYYMMDD description6

......

Statement3 -- YYY delete YYYYMMDD description7

......

......

Statement4 -- description8 (important statement)

......

End

7. Some Comments related rules and Suggestions

(1) unified use of"--"(Do not use"/**/for comment ").

(3) Each script segment must be annotated before it completes certain functions (for example, creating a data table, storing a process, a task, and inserting a default record.

(4) After creating each field in the data table, there should be a comment indicating the meaning of the field, and some also need to specify the value range.

(5) note each input/output parameter in the creation stored procedure and function, indicating the parameter meaning, and specifying the value range.

(6) Comment on Branch statements (including condition branches) and loop statements.

(7) ensure code and annotation consistency. Modify the code and modify the corresponding comments. comments that are no longer useful must be deleted.

(8) The comment should be similar to the code described in it. The comment on the code should be placed at the top or right side of the Code (the comment on fields in the data table and stored procedure parameters) adjacent to the comment and should not be placed below, if it is placed above, it should be separated by blank lines with the above Code.

(9) comments are scaled in the same way as the described code.

(10) The comments in the Chinese version use the Chinese description and those in the overseas version use the English description.

(11) correct names of functions, procedures, variables, and so on, and reasonable organization of the code structure make the code self-Annotated.

(12) Avoid using abbreviations in comments, especially those that are not commonly used.

8. Summary

Comments are icing on the cake. inappropriate comments may not only play a proper role, but may lead to misunderstandings. Therefore, we must follow the simple, clear, clear, and easy-to-understand principles when adding a script file annotation.

(This series of articles will be updated twice a week, so stay tuned! My microblog: http://weibo.com/zhouzxi? Topnav = 1 & wvr = 5, No.: 245924426, welcome !)