MaixPy programming specification
This is a development guide for MaixPy developers. MaixPy as an open source software, it needs to be completed by different people in a cooperative way. This document is a guide for developers.
MaixPy developers please follow this programming style. At the same time, users who use MaixPy can also use this document to understand some conventions in the MaixPy code so that they can easily grasp the implementation of MaixPy.
1. Normative principles#
- Simple, avoid obscure syntax
- Strict and logical thinking
- Simple, concise naming and refined code
- Performance, optimized by algorithm, compiler and hardware
2. Directory structure && file name#
- Directory Structure
The entire project is divided into subdirectories according to functional modules, and each subdirectory is divided into header files and source file directories to make the structure clear and easy to understand.
If the catalog name has no special requirements, please use all lowercase; the catalog name should reflect part of the meaning, and the components directory can reflect the meaning of components.
- File structure
If there is no special requirement for the file name (if you quote other places, you can keep the corresponding name), please use all lowercase. In addition, in order to avoid the problem of duplicate file names, please try not to use generalized and frequently used names in some places.
3. Header file definition#
C language header files need to define a symbol in order to avoid repeated inclusion. Please use the following definition of this symbol
style of:
That is, "__" is used on both sides of the defined symbol to avoid duplication. In addition, it can also be changed according to whether the file name contains multiple words.
Use "_" to connect.
4. File header comment#
The header of each source file should include the corresponding copyright information, Change Log record:
For example, the above form is adopted.
5. Structure definition#
Please use lowercase English names for structure names, and use "_" to connect words to words, for example:
Among them, "{", "}" occupies a line independently, and the following member definitions are defined by indentation.
For the type definition of structure, please use the structure name plus "_t" as the name, for example:
6. Macro definition#
In MaixPy, please use uppercase English names as macro definitions, and use "_" between words to connect, for example:
7. Function name, declaration#
Please use lowercase English for the function name, and use "_" to connect between words. Provide APIs for upper-level applications
Interface must be declared in the corresponding header file; if the function entry parameter is empty, void must be used as the entry parameter
Number, for example:
8. Comment writing#
Please use English as comments. Using Chinese comments will mean that you need to switch back and forth between Chinese and English input methods when writing code to interrupt the idea of writing code. And the use of English annotations can better communicate with technicians outside of China.
There should not be too many comments on the source code. More explanation should be what the code does. Only when individual key points need some corresponding suggestive comments to explain how a complex algorithm works. Comments on the statement can only be written above or on the right, other positions are illegal.
9. Indentation and branching#
Please use 4 spaces for indentation. If there is no special meaning, please branch after "{" and use indentation on the next line, for example:
The only exception is the switch statement. The switch-case statement uses the alignment of the case statement with the switch.
E.g:
The case statement is aligned with the previous switch statement, and the subsequent statements are indented.
On the branch, if there is no special consideration, please do not use more than two blank lines in a row in the code.
10. Braces and spaces#
From the perspective of code reading, it is recommended that each curly brace occupy a separate line instead of following the statement, for example:
The matching braces occupies a single line, and the code will have a corresponding level when reading it without confusion.
Space It is recommended to leave a space before the non-function bracket call to distinguish it from the previous one, for example:
It is recommended to leave a space before the brackets (including if, for, while, switch statements involved), and a space between the operator and the string in the operation expression. In addition, do not leave spaces on both sides of the expression in parentheses, for example:
The spaces on both sides of the brackets are not allowed.
11. log information#
In MaixPy, the commonly used log method is printk, and the py terminal is mp_print, and after we increase or decrease the MaixPy function, it is recommended to delete or comment out the unnecessary printk
But note, the final submitted code cannot contain printk
and printf
functions, they can only be used during debugging! ! ! Otherwise it will cause disconnection when using the IDE
The log output should be designed to be turned off under normal circumstances (for example, it can be turned on by a variable or macro), and
When the log is actually output, the log is an easy way to understand and locate the problem. The "heavenly book" log system is bad and unreasonable.
12. Function#
In kernel programming, functions should be as concise as possible and only complete relatively independent simple functions. The implementation of the function should not be too long, and the implementation of the function should be too long. You should reflect on how you can modify (or split) the function to make the function more concise and understandable.
13. Use astyle to format code automatically#
parameter:
14. Specification Reference#
AliOS-Things - 《AliOS Things Coding Style Guide》
RT-Thread - 《RT-Thread Programming Style》
Related Issues not found
Please login GitHub to create issue