Software coding specification preface:
By establishing code writing specification, forming BCB development team coding conventions, improving program reliability, readability, modification, maintainability, consistency, ensuring the quality of program code, inheriting software development results, and makes full use of resources. Improve the inheritance of the program so that the results of the developers can share.
Software coding To follow the following principles:
1. Follow the development process and write code under the guidance of the design.
2. The writing of code is to achieve the functionality and performance of the design, requiring the correct completion of the design requirements to achieve the performance of the design.
3. The program has a good program structure, improves the program's packaging, and reduce the degree of coupling of the program.
4. Program is responsible, easy to understand; convenient debugging and testing, tested.
5. Easy to use and maintain; good modifications, expandability; reusability / graft.
6. Small resources and complete the task at low cost.
7. Without reducing the readability of the program, try to improve the execution efficiency of the code.
The description of this specification is mainly taken as a Borland C Builder language as an example.
1. Specification: The following detailed description will be described below.
1: Document management of the source program:
a) Organization: Each program file unit usually consists of .cpp, .dfm, and .h and other files and puts the public declaration portion of the unit in .h file. The division unit is mainly based on the class. In principle, each larger class should be a separate unit, but there can be a few classes in the case of smaller and multiple small relationships. Only use of more common classes that have been tested in detail).
b) Name: The original program file named uses meaningful format. For example, the naming of the landing program should be like this, .cpp is login.cpp .dfm is login.dfm .h is login.h
c) File Structure: Each program file consists of three parts: the title, content, and additional instructions.
(A) Title: The foregoing annotation instructions in the document, the contents mainly include: program name, authors, version information, brief description, etc., if necessary, there should be more detailed instructions (will be separated by empty lines in this section) .
(B) Content: For the file source code, the order of the pre-processing statement, the type definition, variable definition, function prototype, function is implemented (only for .cpp file only). MAIN, WINMAIN, control registration and other functions should be placed in the final portion of the content section, the class defines the order of private, protected, public, __pubished, and try to keep every part of one, according to data, functions, attributes, events order.
(C) Additional description: Supplementary description at the end of the file, such as reference materials, etc. If the content is not much, it can be placed in the final section.
for example:
/ ************************************************** ************
Class: Class TimageManipulation
Designer: lunhongjun (2001/05/09)
Uses: For image processing, implement image brightness, contrast, anti-white, color balance
version:
1.0 2001/05/09 Complete the basic image processing function design
2001/05/10 Modify a small bug.
*********************************************************** *********** /
Class TimageManipulation
{
Private: // define variantgraphics :: tbitmap * psourcebitmap; // Used to store unprocessed original images
Graphics :: Tbitmap * PmanipulatedImage; // Store the processed image by deposit
// related parameters during image processing
INT Ibrightness; // Color brightness
Int icontrast; // color contrast
INT IredColorBalance; // Red Color Balance
INT IBLUECOLORBALANCE; / / Blue Color Balance
Int igreencolorbalance; // Green color balance
Bool brotate; // font rotation degree
Bool bmonochrome; // Whether to reveal
Private:
Void __fastcall badhesimage (void); // Adjust image brightness
Void __fastcall contrastimage (void); // Adjust image contrast
Void __fastcall domanipulationImage (void); // Image processing
Void __fastcall monochromeImage (void); // image
Void __fastcall docolor (void);
Void __fastcall DOFILTER (INT * FLT, INT DIV);
void __fastcall rotateImage (void); // Adjust image color balance
Public: // Define Property, Method, Event, Function
__fastcall timageManipulation ();
__fastcall ~ timageManipulation ();
Void __fastcall dobrightness (int BrightnessIncrement);
Void __fastcall docontrast (int ContrastIncrement);
Void __fastcall Domonochrome (Void);
Void __fastcall dochangecolorbalance (int Redbalance,
INT bluebalance, int Greenbalance;
Void __fastcall setsourceImage (Classes :: TPERSISTENT * SOURCE);
Graphics :: tbitmap * __fastcall getmanipulationImage (void);
Void __fastcall doblur (void);
Void __fastcall dosharp (void);
Void __fastcall doemboss (void);
Void __fastcall loadimagefromfile (ANSISTRING FILENAME);
Void __fastcall savemanipulatedImageAsfile (ANSISSTRING FILENAME);
TIMAGEMANIPULATION & OPERATOR = (const timageManipulation & imp);
Void __fastcall dorotate (void);
}
#ENDIF
2. Edit style:
(1) indent
The indentation is in 4 spaces. It is recommended to set the Block IDent of the General page in Tools / Editor Options to 4, Tab Stop to 4, do not select Use Tab Character. Pretreatment statements, global data, function prototypes, headings, additional instructions, function description, label, etc. are written. The "{" "}" pair alignment is aligned, and the statement of the statement block class is suggested for each "{" "}" separately. (2) space
Variables, classes, constant data, and functions are aligned between their type, modification (such as __fastcall, etc.) and is aligned. The keyword principle is empty, such as if (...), etc., the operator is equipped with: "::", "->", "[", "]", " ", " "," ~ ","! "," "," - "(pointing)," * "," * "," * "(referring to the pointer) and other operators do not add Space (in which the single-grade operator is connected to the operand), other operators (including most bubble operators and three-metron operators "?:" Extraordin in both sides "(", ") "The operator is aligned in its inner side, and it can be aligned in the case when the function is defined, but can not be used when the function is implemented.", "The operator is only one after it, it needs to be aligned. It can also be empty or more spaces, the "SIZEOF" operator is recommended to be in its back, whether there is a parentheses, the application of the comments added after the statement, separated by the statement and aligned as much as possible.
(3) Alignment
In principle, the relationship is closely related to the alignment, including type, modification, name, parameter, etc. are aligned. The length of each row should not exceed too much screen. If necessary, the wrap is appropriate, when the wrap is as possible, "," or operator, it is best to take the operator after the wrap, and the following lines are in the first line of this statement. Injunction, but the statement is still subject to the indentation of the first line, that is, the next line is "{" should be aligned with the first line.
The variable definition is preferably aligned by adding spaces, and the same type of variable is preferably placed together. As shown in the following example:
Int value;
Int result;
Int length;
DWORD size;
DWORD BUFSIZE;
Char * pbuf;
Void * poutputbuf;
LPCSTR * PPATH;
(4) blank line
There are two lines between the part of the program file structure. If it is not necessary, it can only be empty, and each function is realized, and the BCB will automatically generate a line of "// ------" to separate, Because each function must have a function description annotation, it is usually only empty or not, but at least a row should be navigated to the case where there is no function description. For your own functions, it is recommended to share "// ------". The function internal data and the code should be at least one line, and the code should be spaced in the code. It is recommended to have a variable declaration in the code in the code. At least four "P" in the class, there is also a space between the data and the function therein.
(5) Comment
There is the following three points for the comment:
A. Must be meaningful.
B. The program must be described correctly.
C. Must be the latest.
Note is essential, but it should not be too much. The following is four essential notes:
A. Title, additional instructions.
B. Function Description. For almost every function, there should be an appropriate description, usually before the function implementation, before the function implementation part, the content is mainly the function, purpose, algorithm, etc. of the function, the parameter description , Return value description, etc., there must be some instructions such as special hardware and software requirements if necessary. C. There must be some instructions in the code that does not clearly or inlet.
D. and a small amount of other comments.
Note There is two kinds of bidders and line bets, which refers to: "/ ** /" and "//" recommendation to a block annotation, D line notes, B, and C depend on the situation, but should be unified, At least Class B annotation in one unit should be unified.
For example, as follows:
/ ************************************************** **********************************
Function Name: ResultType Myfunction (paramtype1 param1, paramtyp2, param2)
Function: This function is mainly the following functions.
Design purpose: Designing this function is mainly for solving. . .
Design principle: This function is designed. . .
Implementation method / process: In order to implement the purpose of functions, this function is implemented. . .
Export parameters:
ParamType1 param1: Type ParamType1, this parameter is. . .
. . .
Return value description:
Design modification log:
2001/4/16 First Design
2001/4/17 revised. . .
2001/4/18 added. . . deleted. . .
related functions:
Other supplementary descriptions:
*********************************************************** *********************** /
ResultType Myfunction (paramtype1 param1, paramtyp2, param2)
{
Int value;
Int result;
DWORD size;
Char * pbuf;
. . . .
}
(6) Code length:
For each function, it is recommended to control the length of about 53 rows as much as possible, and the code for more than 53 rows should be reconsider to split it into two or more functions. The function split rules should not undermine the original algorithm, and the part of the split should be reused. For repetitive code to be used in multiple modules or forms, it can be independently become a function with public nature, placed in a common module (Common.cpp / Common.h)
3. Name of symbol names (including variables, functions, labels, module names, etc.)
Select the actual English logo symbol or abbreviated symbol, the name does not use arabic number as much as possible, such as this name is not advocated: Value1, Value2, Value3, Value4 ...
E.g:
File (file), code (number), data, pagepoint, Faxcode, Address, Bank (Bank), ...
Variable Name: Composition from (prefix modifier).
(1) Survival period modification: Use L (local) to represent a local variable, p (public) represents global variables, s (send) represents parameter variables
(2) Type modification: Use S (ANSISTRING) to represent strings, C (char) represents characters, n (Number) value, i (int GER) represents an integer, D (Double) represents double precision, F (float) floating point type , B (BOOL) Boolean, D (DATE) represents a date type. For example:
LI_LENGTH represents the local variable of the plastic, which is used to identify the length of the length of the local area variable, which is used to identify the code.
Control Name: Composition by (prefix modifier). The prefix is the name of the control.
Button variable Button XXXXXXX, for example: Buttonsave, ButtoneXit, ButtonPrint, etc.
Title variables Label XXXXXXX, for example: labelname, labelsex, etc.
Data table variable Table XXXXXX, for example: TableFile, TableCount, etc.
Query xxxxxx, for example: queryfile, querycene, etc.
Data source variable Datasource XXX, for example: DataSourceFile, DataSourceCenter, etc.
. . . . . . . . . . . . . . . .
(Note: It is best to use the table name for the "modifier" section related to the table.)
4: Input and output
The input and output methods and formats are convenient as soon as possible, avoiding trouble due to improper design. Programs should be developed according to the type, characteristics and different requirements of different users. The format is simple and there should be complete error checks and error recovery.
The interface layout mainly considers the placement of the screens in the screen. User users can find the operation objects in the fastest speed, discover the target, and the screen's layout should consider the expression of the interface, so that the interface is beautiful and coordinated. Interface design requirements meet the following requirements:
● Only necessary information on the interface.
● All necessary information is included on the interface.
● The interface layout starts from the upper left corner.
● Develop format standards, all screen design comply with these standards, maintain consistency.
● Put the relevant information based on logical relationships.
● The screen design should maintain a symmetrical balance.
● Avoid excessive use forwarding information. // For example, the OneNTER event is used as little as possible.
● Distinguish title and content.
● The prompt information is simple.
● Design is consistent with user knowledge and experience.
● Display information in order of use.
● Follow the factual standards of popular software.
● Select a reasonable display method.
● Do not let the user switch on the screen as much as possible to complete a complete operation.
5: Other program skills
Programs increase reasonable amount of annotations. The annotation of the program is an important indicator for evaluation assessment.
In the program design, it should be considered in a comprehensive consideration of the processes that may exist. There should be a good error handling and exception processing mechanism. It will ensure that the program can run / exit when the error is wrong, and does not cause the user's data loss / loss. For unexpected errors or exceptions, it is necessary to record the operating conditions at the time and the user can return this information to the developer.
Avoid using similar variable names, try not to include numbers in variables.
Don't have a variety of meaning.
Show all variables.
Pay attention to the error of floating point operations, less floating point number.
Pay attention to the characteristics of integer operations.
Use less or without goto statement, do not cross each other.
Try to use less globally and static variables.
Improve program encapsulation and reduce the coupling of each module of the program.
Improve the inheritance of the program, establish a general function library, control library, so that the results between developers can share.
Description: This document designer: Luhongjun (over Jiang Bao Yu). Document copyright belongs to the BCB development team, you are welcome to reprint the reference, but please indicate the document owner and the designer. Do not modify it without consent, it is not available for commercial purposes.
