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.
Post History
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 stan...
Answer
#3: Post edited
- 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/or 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.
- 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.
#2: Post edited
- 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/or 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 put a company-prefix before the module prefix, even for smaller embedded systems, in case code from various sources (suppliers) had to be brought together.- ---
- 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.
- 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/or 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.
#1: Initial revision
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/or 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 put a company-prefix before the module prefix, even for smaller embedded systems, in case code from various sources (suppliers) had to be brought together. --- 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.