articles in variable names and hard-coding strings

Question

re-edited by author: no this is not 2 questions. This is one question about code review questions containing two separate points. Please do not edit my question.

For naming variables, the two sides are regarding using articles (a, an, the) in the variable name (e.g. theBook vs. book -or- parseTheString vs. parseString).

For hard-coding strings, the three sides are whether to put all strings into constants (public static final) in a separate file (class or interface), put them all in the same file (private static final), or don't use constants for strings at all. (e.g. new Button("Click Me") vs. new Button(BUTTON_LABEL_CLICK)). We also discuss the Hungarian notation issue quite a bit but I've seen that discussed here in other questions.

For a very long time it has been the defacto standard to not use articles in variable names (adds visual clutter without adding value) and to not have hard-coded strings sprinkled through the source code (a potential maintenance nightmare and very poor for internationalization). Now we are starting to see violations of these and the developers seem truly surprised when someone marks these as defects or at least needing attention. The manager has said they don't care one way or the other and these points are not in our company coding standards.

Answer 1

Articles in Variable Names

They add little to no value in most cases, but make the code longer to read.

Usually, I'd rarely have a the need for the distinction between a "a" or "the" in the flow of a function, so it doesn't make sense to use articles.

It's a formal programming language and I am fine with it not reading exactly like a natural language. In fact, it's probably better this way, not everything's necessarily so great about natural languages.

There are a few cases where readability can benefit from using articles though, for instance if you want to implement a checker for a "is a" relationship with a method signature like boolean isA(Object o, Class<?> cl) ^{(I'm not advocating this to be a good idea)}.

Hard-Coded Strings

It depends on whether you plan to reuse them or not, and whether that reuse is driven by semantics (and not just the fact that the String has the same content in different places) and spread across multiples classes or sub-systems.

To that extent, I usually use these rules:

1. If you have the same string multiple times and it has the same meaning acros multiple classes, then extract to constants in an interface.

2. If you have the same string multiple times within a single class and it has the same meaning within that class, then extract to constants within the class.

3. If you have only a few number of repetitions of as tring, or they just happen to be identical but aren't guaranteed to always be in the future, then I'd leave them inlined.

4. If any of the above would render maintenance difficult, screw rules 1 to 3 and do whatever works best for you.

Of course, make sure that the constant's name makes the code as semantically valid as the string it holds. That also applies for other things that aren't strings (like Predicates, for instance).

Answer 2

For hard-coding strings, the three sides are whether to put all strings into constants (public static final) in a separate file (class or interface), put them all in the same file (private static final), or don't use constants for strings at all. (e.g. new Button("Click Me") vs. new Button(BUTTON_LABEL_CLICK)). We also discuss the Hungarian notation issue quite a bit but I've seen that discussed here in other questions.

If you want a high-quality user experience, anything that is presented to the user (button labels, error messages, etc.) must be reviewed by the UI designer. In my experience, when developers are hard-coding text, that doesn't happen. The developers do the best they can, but the result is a set of messages and labels that are little better than random.

Answer 3

Apple use articles - inconsistently - in their ObjC code. It adds nothing to the legibility of their code or the descriptiveness of their variable names:

- (id)viewWithTag:(NSInteger)aTag;
- (id)initWithFrame:(NSRect)frameRect mode:(int)aMode cellClass:(Class)factoryId numberOfRows:(int)rowsHigh numberOfColumns:(int)colsWide;

Note aTag and aMode vs frameRect.

I hate the semi-standard and don't use it. It makes the code sound moronic.