search

SymbiSoft / mosync

Automatically exported from code.google.com/p/mosync
0 stars 0 forks source link

Rename textbox constants (and other abbreviated constants) to readable names #975

Open GoogleCodeExporter opened 8 years ago

GoogleCodeExporter commented 8 years ago 
What steps will reproduce the problem?
1. Open tools/ild2/maapi.idl
2. Locate constsets MA_TB_*
3. These names are totally unreadable, it is not at all clear that "TB" means 
"TEXTBOX"
4. There are several other abbreviated constant names that should be deprecated 
and renamed to improve readability.

What is the expected output? What do you see instead?
I expect names to be readable and read fluently. Now I see lots of 
abbreviations, some of which are not obvious. With the names we have now, we 
potentially force many thousands of programmers to look up the documentation to 
understand a name that could be self documenting. If a line of code becomes too 
wide because of long constant names, then simply use multiple lines.

I have looked through the constset names and sometimes the prefix "MA_" is used 
and sometimes not. Suggest dropping these prefixes, as they do not add to 
readability. If names should clash with application code, the application code 
has to take that hit and be updated. Alternatively, add prefix "MA_" to all 
constsets.

Suggested names:

MA_TB_TYPE_ --> TEXTBOX_TYPE_
MA_TB_RES_ --> TEXTBOX_RESULT_
MA_TB_FLAG_ --> TEXTBOX_FLAG_

RT_ --> RESOURCE_TYPE_

MA_LOC_ --> LOCATION_
MA_LPS_ --> LOCATION_PROVIDER_

AUDIO_FMT_ --> AUDIO_FORMAT_

MA_CAMERA_FORMAT_ --> CAMERA_FORMAT_

MA_PIM_* -> PIM_* (PIM is an established TLA that we don't need to spell out)

Original issue reported on code.google.com by mikael.k...@gtempaccount.com on 25 Nov 2010 at 9:43

GoogleCodeExporter commented 8 years ago 
Assigning this to QA since it is a an important quality issue to have an 
understandable API.

Original comment by mikael.k...@gtempaccount.com on 13 Jan 2011 at 3:02

GoogleCodeExporter commented 8 years ago 
The MA_ prefix should remain as this is part of our standard naming convention 
to signify that these are MoSync and not user defined constants.  The 
abbreviations however should be expanded to something meaningful as this 
definitely impedes readbility

Original comment by miles.mi...@gtempaccount.com on 27 Apr 2011 at 7:31

GoogleCodeExporter commented 8 years ago 
Clearly the old constant definitions must remain and marked as deprecated

Original comment by miles.mi...@gtempaccount.com on 27 Apr 2011 at 7:33