Standardize parameters ordering in some typical cases to minimize confusion.
Signed-off-by: Yury Norov (NVIDIA) <[email protected]> --- Documentation/process/coding-style.rst | 48 ++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst index d1a8e5465ed9..dde24148305c 100644 --- a/Documentation/process/coding-style.rst +++ b/Documentation/process/coding-style.rst @@ -523,6 +523,54 @@ below, compared to the **declaration** example above):: ... } +6.2) Function parameters order +------------------------------ + +The order of parameters is important both for code generation and readability. +Passing parameters in an unusual order is a common source of bugs. Listing +them in standard widely adopted order helps to avoid confusion. + +Many ABIs put first function parameter and return value in R0. If your +function returns one of its parameters, passing it at the very beginning +would lead to a better code generation. For example:: + + void *memset64(uint64_t *s, uint64_t v, size_t count); + void *memcpy(void *dest, const void *src, size_t count); + +If your function doesn't propagate a parameter, but has a meaning of copying +and/or processing data, the best practice is following the traditional order: +destination, source, options, flags. + +for_each()-like iterators should take an enumerator the first. For example:: + + for_each_set_bit(bit, mask, nbits); + do_something(bit); + + list_for_each_entry(pos, head, member); + do_something(pos); + +If function operates on a range or ranges of data, corresponding parameters +may be described as ``start - end`` or ``start - size`` pairs. In both cases, +the parameters should follow each other. For example:: + + int + check_range(unsigned long vstart, unsigned long vend, + unsigned long kstart, unsigned long kend); + + static inline void flush_icache_range(unsigned long start, unsigned long end); + + static inline void flush_icache_user_page(struct vm_area_struct *vma, + struct page *page, + unsigned long addr, int len); + +Both ``start`` and ``end`` of the interval are inclusive. + +Describing intervals in order ``end - start`` is unfavorable. One notable +example is the ``GENMASK(high, low)`` macro. While such a notation is popular +in hardware context, particularly to describe registers structure, in context +of software development it looks counter intuitive and confusing. Please switch +to an equivalent ``BITS(low, high)`` version. + 7) Centralized exiting of functions ----------------------------------- -- 2.43.0
