|
Code should be as self documenting as possible. Having simple, descriptive names for your methods, classes, and more importantly your variables is critical, and is key with self documenting code.
var serviceTypes = new List<ServiceType>();
instead of:
var st = new List<ServiceType>();
|
|
|
|
|
I've been working on retiring some VBA code out of critical business processes. One of the previous incumbents was a great lover of single character variable names and two character function names.
I have actually seen something along the lines of
Dim s As Range
s = gr() Every. Other. Module. has s As String 
|
|
|
|
|
Some programmers are unable to control themselves, thinking that "Longer is better - unconditionally and always!"
So they consider the variable name 'Price_paid_for_the_product' to be far better than 'Price'. To turn on that visual signal labeled 'LED1' on the circuit board, they insist to program 'Light_emitting_diode_one = On' rather than 'LED1 = On'.
I was in a project at a time when the company programming style standards were revised. Our project leader granted an exception from one of the coding rules: No statement longer than 80 characters. The problem was that the project naming rules frequently lead to names exceeding 80 characters. I never thought that those names improved readability.
In other projects, I have implemented protocol standards where the standard defines a set of states and a set of events identified by abbreviations / acronyms of 3-5 characters, predicates identified as p01 to p67. When you make a direct implementation of this standard, it would be silly to attempt to de-abbreviate or de-acronymize state and event names and make up some strange, unknown 'descriptive' name for the predicates, in order to 'improve the readability' of the code. It strongly distorts the reading of the code.
I have similar problems with papers and articles that seem to think that the reader (presumably a professional, or at least semi so) is completely unfamiliar with basic, well established terms. So throughout the text, they write e.g. 'CPU (Central Processing Unit)' and 'DMA (Direct Memory Access)' and 'RAM (Random Access Memory)' - not only when the term is introduced, but throughout! I get the feeling that these people would write 'VB6 (Visual Beginners All-purpose Symbolic Image Code Version 6)' on every reference to VB6 as well ...
So please: Use common sense. When 'readability' has reached the level of 'no ambiguity whatsoever', there is no need to use a phrase rather than a name to refer to a variable, value or object.
|
|
|
|
|
Well there is an acceptable balance.
I come from the shorthand generation (and I'm kinda getting the hang of camelCase). I vaguely remember a convention about anything starting with uppercase is a function and lowercase is a variable, and it extends to objects as well (objects are just another form of data structure with pointers to functions)
That said, reading the context of a program, one can easily understand
gmTabWidgetL to be "GeoMechanical tabulation widget, on the Left" (it's gui code). The word Geomechanical is in both a comment and in a text label before the code.
So that's pretty well documented I'd say.
But rather unfortunately Python doesn't use types to declare variables so figuring out that thing was an object requires some detective work in finding the assignment of the name and the object's constructor.
In the end I think people who can't be bothered with deducing a variable's full name or function, should consider alternative careers. Computer programming is about instructing the calculator what to do, not chatting with the layman.
|
|
|
|
|
Outdated options - in modern languages you have thousands of options for single letter names, not just 26. Hieroglyphs always makes the code look nicer - and you can of course throw in the odd Klingon character just to spice it up a bit.
|
|
|
|
|
|
Both of those problems are most easily solved by using either the standard library function or the appropriate operating system API.
Not because either of those solutions are likely to be correct, but because when their irredeemable broken-ness is discovered, you can invoke THE MIGHTY FINGER OF BLAME and point.
Software Zen: delete this;
|
|
|
|
|
The Turkish I is not solved by using a standard library. All the libraries / OS can do is offer different ways of comparing and then the developer needs to choose the right one. Luckily in most cases it not too hard to figure out (if you are aware of it), but not always - and even if you are aware it is an extremely easy area to make a mistake that will not be found before someone runs it in Turkey.
Same for time zones. For example: what does it mean if only the date component is entered? Should it be seen as covering the 24 hours time period where the operation was performed? Where the server was (or other "main time-zone of the project")? Or could it be the entire 48 hour interval it is that date somewhere. Sure the libraries can help you implement the right solution, but they can't determine what is correct.
|
|
|
|
|
I'll add another problem not solved "by using either the standard library function or the appropriate operating system API": Alphabetic ordering. Going beyond A-Z, different languages may have common extensions. E.g. Norwegian has '..xyzæøå', while Swedish has '...xyzåäö'. Historically, æ is the same character as ä, ø the same as ö. (In old Norwegian writing, you frequently encounter ä and ö.)
Everything is fine as long as you sort a list list of either Norwegian or Swedish words (typically: names), but what if the the list contains both Norwegian and Swedish names? Should 'Örnes' be sorted before or after 'Årnes'? Should 'Ørnes' be sorted before or after 'Årnes'? What about the Norwegian name 'Ørnes' in the old Norwegian spelling 'Örnes': Should it be sorted after 'Årnes' because the Swedes would do it that way, even though Sweden/Swedish was never in question?
You could evade the problem by saying: If you address a Norwegian audience, you sort ä and ö like æ and ø. If you address a Swedish audience, you sort æ and ø like ä and ö. If you address an English-speaking audience, how to you do the sorting?
Similar issues occur with some languages where a few double characters are sorted in special ways. I believe (correct me if I am wrong) that in Spanish, 'll' is sorted after all other 'l?'s (i.e. 'l' followed by any other character than 'l'), but before any 'm'. In French, there are numerous words of the same alphabetic characters, but with different accents; the accents have a well defined ordering sequence. In other languages, accents do not affect alphabetic ordering. So should or shouldn't you consider accents when ordering?
There is of course the ostrich (also known as 'US') solution: "Well, that is your problem!" And it is, but that doesn't solve the problem. It is still there, in spite of standard library functions and operating system APIs.
|
|
|
|
|
These problems are hard for people without relevant cultural background. Hence if you want to service a certain market, you need a consultant from that market in order to iron out such problems. They usually are not hard to solve, just hard to foresee for someone outside of a particular culture. Of course, the cost of adding such quirks may be surprisingly high.
|
|
|
|
|
We have a payment processor that has problems with single right quotes, and the letters with accents. I tried and failed to get the code to find the single right quotes to replace them 
I can't think of another coding problem that I was incapable of solving.
|
|
|
|
|
The timezone video omitted a couple of issues that would make any sane person pull their hair out. Before the introduction of standard time zones, each community set their clock themselves, so that, for example, in Washington DC it might be 9:00 AM, but in Baltimore it might be 9:02 AM. Worse was the use of Arabic time, which survived in Saudia Arabia until 1968, but was used widely all over the middle east. In this scheme, 12:00 was set each day at sundown. Which would not only change based on latitude and longitude, but also on the day of the year. I can't even imagine trying to code for that. I'd be surprised if even the best timezone libraries handle it.
Keep Calm and Carry On
|
|
|
|
|
Is Chris Maunder trying to test us whether we're paying attention or not?
|
|
|
|
|
Nope, he joined the Spanish Inquisition.
Their chief weapon: surprise and fear, fear and surprise.
Their two weapons are fear and surprise...and ruthless efficiency...
Their three weapons are fear, surprise, and ruthless efficiency... and an almost fanatical devotion to Bob.
GCS/GE d--(d) s-/+ a C+++ U+++ P-- L+@ E-- W+++ N+ o+ K- w+++ O? M-- V? PS+ PE Y+ PGP t+ 5? X R+++ tv-- b+(+++) DI+++ D++ G e++ h--- r+++ y+++* Weapons extension: ma- k++ F+2 X
|
|
|
|
|
Quote: There are 2 hard problems in Computer Science: caching, naming and off-by-one errors
Freedom is the freedom to say that two plus two make four. If that is granted, all else follows.
-- 6079 Smith W.
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
