@@ -206,33 +206,65 @@ adhere to the existing style and use `tools/codeformat.py` to check any changes.
206206The main conventions, and things not enforceable via the auto-formatter, are
207207described below.
208208
209- White space:
209+ As the MicroPython code base is over ten years old, not every source file
210+ conforms fully to these conventions. If making small changes to existing code,
211+ then it's usually acceptable to follow the existing code's style. New code or
212+ major changes should follow the conventions described here.
213+
214+ ## White space
215+
210216- Expand tabs to 4 spaces.
211217- Don't leave trailing whitespace at the end of a line.
212218- For control blocks (if, for, while), put 1 space between the
213219 keyword and the opening parenthesis.
214220- Put 1 space after a comma, and 1 space around operators.
215221
216- Braces:
222+ ## Braces
223+
217224- Use braces for all blocks, even no-line and single-line pieces of
218225 code.
219226- Put opening braces on the end of the line it belongs to, not on
220227 a new line.
221228- For else-statements, put the else on the same line as the previous
222229 closing brace.
223230
224- Header files:
231+ ## Header files
232+
225233- Header files should be protected from multiple inclusion with #if
226234 directives. See an existing header for naming convention.
227235
228- Names:
236+ ## Names
237+
229238- Use underscore_case, not camelCase for all names.
230239- Use CAPS_WITH_UNDERSCORE for enums and macros.
231240- When defining a type use underscore_case and put '_ t' after it.
232241
233- Integer types: MicroPython runs on 16, 32, and 64 bit machines, so it's
234- important to use the correctly-sized (and signed) integer types. The
235- general guidelines are:
242+ ### Public names (declared in headers)
243+
244+ - MicroPython-specific names (especially any declared in ` py/ ` and ` extmod/ `
245+ directories) should generally start with ` mp_ ` or ` MP_ ` .
246+ - Functions and variables declared in a header should generally share a longer
247+ common prefix. Usually the prefix matches the file name (i.e. items defined in
248+ ` py/obj.c ` are declared in ` py/obj.h ` and should be prefixed ` mp_obj_ ` ). There
249+ are exceptions, for example where one header file contains declarations
250+ implemented in multiple source files for expediency.
251+
252+ ### Private names (specific to a single .c file)
253+
254+ - For static functions and variables exposed to Python (i.e. a static C function
255+ that is wrapped in ` MP_DEFINE_CONST_FUN_... ` and attached to a module), use
256+ the file-level shared common prefix, i.e. name them as if the function or
257+ variable was not static.
258+ - Other static definitions in source files (i.e. functions or variables defined
259+ in a .c file that are only used within that .c file) don't need any prefix
260+ (specifically: no ` s_ ` or ` _ ` prefix, and generally avoid adding the
261+ file-level common prefix).
262+
263+ ## Integer types
264+
265+ MicroPython runs on 16, 32, and 64 bit machines, so it's important to use the
266+ correctly-sized (and signed) integer types. The general guidelines are:
267+
236268- For most cases use mp_int_t for signed and mp_uint_t for unsigned
237269 integer values. These are guaranteed to be machine-word sized and
238270 therefore big enough to hold the value from a MicroPython small-int
@@ -241,11 +273,13 @@ general guidelines are:
241273- You can use int/uint, but remember that they may be 16-bits wide.
242274- If in doubt, use mp_int_t/mp_uint_t.
243275
244- Comments:
276+ ## Comments
277+
245278- Be concise and only write comments for things that are not obvious.
246279- Use ` // ` prefix, NOT ` /* ... */ ` . No extra fluff.
247280
248- Memory allocation:
281+ ## Memory allocation
282+
249283- Use m_new, m_renew, m_del (and friends) to allocate and free heap memory.
250284 These macros are defined in py/misc.h.
251285
0 commit comments