Welcome to Software Development on Codidact!
Will you help us build our independent community of developers helping developers? We're small and trying to grow. We welcome questions about all aspects of software development, from design to code to QA and more. Got questions? Got answers? Got code you'd like someone to review? Please join us.
Comments on C naming convention, module trigrams?
Parent
C naming convention, module trigrams?
For my company, I'm writing naming conventions for embedded code in C language.
- Function names must be named in lowerCamelCase() and start with a verb.
- Global variables are in Maj_started_lower_case and are noun groups.
Exemple:
void initCanDriver();
uint8_t *Can_driver_buffer;
I have propositions to start our names with a module trigram? Exemple:
void CDR_init();
uint8_t *CDR_buffer;
Pros of trigram methode:
- clearly identify modules (and force to have modules)
- avoid duplicate names
Cons of trigram methode:
- actually, the majority of our codes don't really have modules, how to name a new function inside? We would have to define all modules.
- often less readable [you have to know CDR is CAN Driver]
Do you think it is a good idea?
Post
Starting with the goals: A naming convention typically aims at supporting several, partly contradictory goals, among which are the following:
- Compliance with the limitations of the language standard and possibly other standards that apply. There are many symbols that are reserved by the ISO-C standard.
- Avoid name clashes between code pieces. This can be code from different supplier companies, but even code from different teams. The risk of name clashes increases with scope, but also with the degree of re-use of the respective code in different contexts.
- Clarity ("Use variable names that mean something" - Kernighan and Plauger, 1974)
- Short to reduce typing and (more importantly) reading effort.
- Indicate architectural / module structure.
Particularly the second of the aforementioned points is a good reason to introduce prefixes for globally visible symbols (macros in header files, functions and variables with external linkage, ...), but module prefixes also support the fifth point. You are calling them "module trigrams", but I would recommend to think of them in a more general way:
- Think of them as namespaces that isolate/protect different sets of symbols from each other.
- Do not limit yourself to three letters (could be more, but also less).
- Consider even using them hierarchically.
The last point can be relevant if you need to combine code from different companies or plan your code to be re-used across many projects: I have worked at companies that, for this reason, put a company-prefix before the module prefix, even for smaller embedded systems.
Now, to the contradicting goal of having short names: Prefixes increase symbol length, but they reduce the risk of name clashes. The risk of name clashes, however, is much smaller and more manageable in smaller scopes. For example, local variables don't have to (and should not) follow the same rules, using the prefix approach here is overkill. (Don't forget, it is all about risk - there is no absolute protection: Someone somewhere might still have the great idea to define a macro called "index" in a public header file...)
For symbols with internal linkage (like, static helper functions) there is no simple rule, because depending on how tools like debugger etc. work with the symbol names it may still be beneficial to use the prefixes there as well, and certainly also if you can not exclude the possibility that foreign header files are included into your .c code...
Summary: The use of prefixes is a proven practice to avoid name clashes and show component structure. Understand your goals to see if and how to apply this practice best in your context.
0 comment threads