Changes for page Expressive Names

Summary

• Page properties (1 modified, 0 added, 0 removed)

Details

Page properties

Content

...	...	@@ -1,35 +1,21 @@
1		-Names should be chosen as carefully as one would name their firstborn child.
	1	+Names should be chosen as carefully as the name of your first-born child. It should be obvious from reading the code how it works.
2	2
3		-**Naming Conventions**
4		-
5		-* **Choose Meaningful and Descriptive Names**
6		- * Names should be descriptive of the purpose, e.g., use `unorderedNumbers` and `orderedNumbers` instead of a generic `numbers`.
7		- * Use names that reflect the solution domain and the problem domain.
8		- * Choose one word per concept (e.g. consistently use 'fetch' for the same concept, rather than mixing 'fetch' and 'retrieve').
9		-* **Clarity and Simplicity in Names**
10		- * Names should be self-evident and avoid mental mappings or translations for clarity.
11		- * Avoid ambiguities, such as confusion with similar names or characters (e.g., l and 1, O and 0).
12		- * Make differences clear and avoid very similar expressions.
13		- * Avoid superfluous or redundant context; shorter names are better as long as they are clear.
14		-* **Practical Aspects of Naming**
15		- * Use pronounceable names so that you can easily talk with others about it.
16		- * Use searchable names, meaning names which prevent search conflicts.
17		- * The length of a name should correspond to the size of its scope. E.g. counters only used locally in loops, could be short or even single letters, but names used in a broad scope should be more descriptive and longer.
18		- * Avoid encodings, such as references to the variable's scope or type in its name.
19		-
20		-**Class and Method Naming**
21		-
22		-* **Class Names**
23		- * Should consist of nouns or noun phrases.
24		-* **Method Names**
25		- * Should consist of verbs or verb phrases.
26		- * Follow the JavaBean standard for accessors, mutators, and predicates (prefixes: get, set, is, has).
27		- * Use distinct names for overloaded constructors and prefer private constructors with distinct factory methods.
28		-
29		-**General Coding Practices**
30		-
31		-* **Avoiding Confusion and Misinformation**
32		- * Avoid humorous names, puns, and any names that might cause confusion.
33		-* **Contextual Naming**
34		- * Add meaningful context that complements other variable and method names.
35		- * Dare to rename things for clarity and improvement; colleagues should appreciate these enhancements.
	3	+* **Names describe purpose.** For example, it's better to have a variable `unorderedNumbers`, which is sorted and stored in `orderedNumbers` instead of saving both lists in the same variable `numbers`.
	4	+* **Avoid misinformation.** For example, ambiguities, confusion with similar names or easily confused characters (l and 1, O and 0).
	5	+* **Make differences clear.** Avoid very similar expressions and blank words are redundant (a, an, the, info, data).
	6	+* **Use pronounceable names.** Programming is a social activity that people talk about with others.
	7	+* **Use searchable names. **Searchable means avoiding search conflicts with other independent things with the same name. The length of a name should match the size of its scope. For local counting loops, one letter is sufficient; if the variable is used in several places in the code, it needs a longer name.
	8	+* **Avoid encodings.** There should be no references to the scope or type of the variable in the name.
	9	+* **Avoid mental mappings.** The name of a variable should not require mental effort to understand. For example, unusual abbreviations should be avoided.
	10	+* **Names of classes consist of nouns** or substantivistic expressions.
	11	+* **Method names** **consist of a verb** or an expression with a verb. Accessors, mutators, and predicates should be named after their value and follow the JavaBean standard (prefixes: get, set, is, has). For example, getAge(), setAge(...), isFeatureXEnabled() -> boolean, hasPermission() -> boolean etc.
	12	+* **Use object creation functions rather than overloaded constructors**, as the latter can cause confusion. Overloaded constructors should be declared private, and functions should be used to create instances whose names make the difference clear.
	13	+* **No puns or humorous names.**
	14	+* **Choose one word for each concept.** For example, if you use the word "fetch" once for a particular concept, you should consistently use "fetch" instead of synonyms such as "retrieve".
	15	+* **Avoid ambiguities** as in the word "add" (addition or adding).
	16	+* **Domain-specific terms**
	17	+ * Use terms from the solution domain. Programmers will be reading your code, so use technical language.
	18	+ * Use terms from the problem domain. If there are no computer science terms, at least domain experts can refer to them.
	19	+* **Add meaningful context.** Together with the names of other variables and methods, this context can be created.
	20	+* **Do not add superfluous context.** Shorter names are better than longer ones, as long as they are clear.
	21	+* **Dare to rename things.** Your colleagues should be grateful for improvements.