Policy for style guide: conventions for naming size/number variables #85728

New Issue

Campbell Barton · 2021-02-17T08:22:16+01:00

Campbell Barton commented

2021-02-17 08:22:16 +01:00

Currently there are multiple conventions for naming variables that represent numbers, e.g. (amt, len, ct, cnt, count, sz, tot, num, ...).

Although some are used much more widely than others.

This proposal is to standardize on a fewer terms to be used consistently across the code-base.

NOTE: this is the result of a bf-admins meeting, posting for reference.

Proposal for naming size/number variables

num to specify the number of items in an array or for data-structures that store the number of items.
len for strings (the length of the string without it's null byte, as used in strlen).
size to specify size in bytes.
count for accumulated values (such as the number of items in a linked-list).

These should be used as a suffix, with the name of the values for the prefix, e.g.

/* Struct members. */
struct {
  int *lut;
  int  lut_num;
}

/* Function arguments. */
void function(int *lut, int lut_num);

/* Or functions themselves. */
int BLI_listbase_count(const ListBase *list);
int BLI_ghash_num(ghash);
int BLI_dynstr_len(ds);

Currently there are multiple conventions for naming variables that represent numbers, e.g. (`amt`, `len`, `ct`, `cnt`, `count`, `sz`, `tot`, `num`, ...). Although some are used much more widely than others. This proposal is to standardize on a fewer terms to be used consistently across the code-base. NOTE: this is the result of a bf-admins meeting, posting for reference. ----- **Proposal for naming size/number variables** - `num` to specify the number of items in an array or for data-structures that store the number of items. - `len` for strings *(the length of the string without it's null byte, as used in `strlen`)*. - `size` to specify size in bytes. - `count` for accumulated values *(such as the number of items in a linked-list)*. These should be used as a suffix, with the name of the values for the prefix, e.g. ``` /* Struct members. */ struct { int *lut; int lut_num; } /* Function arguments. */ void function(int *lut, int lut_num); /* Or functions themselves. */ int BLI_listbase_count(const ListBase *list); int BLI_ghash_num(ghash); int BLI_dynstr_len(ds); ```

Campbell Barton self-assigned this 2021-02-17 08:22:16 +01:00

Campbell Barton commented

2021-02-17 08:22:16 +01:00

Changed status from 'Needs Triage' to: 'Confirmed'

Campbell Barton commented

2021-02-17 08:22:16 +01:00

Added subscribers: @ideasman42, @iss, @rjg, @brecht, @mont29, @Sergey, @dfelinto

Campbell Barton commented

2021-02-17 08:34:24 +01:00

These changes where agreed in the bf-admin meeting, flagging the change from _len to _num as causing a fairly huge number edits to existing source code.

I'm not really keen on this change, on the other hand - as part of standardizing on terms, it's OK, I'm not pushing to reverse the decision.

These changes where agreed in the bf-admin meeting, flagging the change from `_len` to `_num` as causing a fairly huge number edits to existing source code. I'm not really keen on this change, on the other hand - as part of standardizing on terms, it's OK, I'm not pushing to reverse the decision.

Bastien Montagne commented

2021-02-17 12:35:19 +01:00

Agreed.

StephanieBogan commented

2021-02-17 20:26:45 +01:00

(Migrated from localhost:3001)

Added subscriber: @StephanieBogan

StephanieBogan commented

2021-02-17 20:26:45 +01:00

(Migrated from localhost:3001)

This comment was removed by @StephanieBogan

*This comment was removed by @StephanieBogan*

Hans Goudey commented

2022-03-28 19:51:43 +02:00

Added subscribers: @JacquesLucke, @HooglyBoogly

Hans Goudey commented

2022-03-28 19:51:43 +02:00

I'd like to propose one small adjustment to the proposal that I talked about with @JacquesLucke.

Generic C++ containers have a standardized size() method that returns how many elements the object contains. This is standard in the STL and other libraries, as well as in our own containers.
I'd like to propose keeping those size() methods for consistency, but only for "generic containers", where "size" couldn't be confused with anything else.

Other than that, it would be good to move this to the style guide so it's easier to find.

I'd like to propose one small adjustment to the proposal that I talked about with @JacquesLucke. Generic C++ containers have a standardized `size()` method that returns how many elements the object contains. This is standard in the STL and other libraries, as well as in our own containers. I'd like to propose keeping those `size()` methods for consistency, but only for "generic containers", where "size" couldn't be confused with anything else. Other than that, it would be good to move this to the style guide so it's easier to find.

Sign in to join this conversation.

No Label

Download

What's New

Blender Studio

Manual

Developers Blog

Documentation

Benchmark

Blender Conference

Development Fund

One-time Donations

Policy for style guide: conventions for naming size/number variables #85728