How do you name your variables and functions (and classes in OO)?
Asuming you had the following two functions; would you call them:
simple_overview()
detailed_overview()or
overview_simple()
overview_detailed()I use the second one. If functions/classes/whatever have similiar uses, then I like it if they start similiar, this makes my code more readable for me.
simpleOverview()
detailedOverview()is what i'd use, because it's easier to remember and write. It also looks prettier.
simple_overview()
detailed_overview()is better, for the simples reason that it is closer to natural language. I used to prefer the >>1 style for word breaks because it is also closer to natural language and does not imply that you should pronounce it as a single word and run out of breath, but Objective-C is sort of ruining my brain in respect to this.
Although Objective-C's hyper-verbose identifiers are sort of nice in that they really do make the code a lot more self-documenting. Instead of a cryptic open_file("blah",M_RDWR), you have an openFileWithFilename:"blah" mode:ReadWriteFileMode. It's more work to type (although Xcode has identifier autocompletion to solve that problem), but it is a lot more self-explanatory and needs far less comments to be understandable.
For functions that don't go outside the module, any old name is good long as it doesn't shadow anything in the standard library. Same thing for any symbol that doesn't end up in a shared library or something.
Exported interfaces' members are prefixed with something sufficiently unique, words separated by underlines.
Only if you don't care about the readability of your code.
>>6
Unreadable code equals job security.
Readability doesn't come from 60-character function names, you silly rabbits.
Seriously. open_file("name goes here", M_RDWR) is cryptic? Do you guys have to use toilet paper that says "ass goes here" on one side, and soil your pants if you're somewhere with only the usual plain white?
If you are intimately familiar with what every part of the code does, anything will be readable. That's not the point. The point is if it's easy to understand for another person, or if it's easy to understand three years later, or if it's easy to understand when you have a project of tens or hundres of thousands of lines of code.
>>10
A programmer should be able to understand that the function open_file will open a file, and that the function to_array converts whatever arguments it is given to an array.
IMO, the functions names length should reflect how complex the function is, if it just does basic stuff, names should be short, like the examples above - not only because it's what they do is basic enough to be easily understood, but also because they ill probably be called a lot. If it does something rather complex, then names can be longer - it probably isn't called too often anyways.
If you actually look at my example, you will see that what the verboseness does is describe the arguments, not the functionality. The part describing the functionality is still "openFile". It also spells out what the constant means instead of relying on a cryptic contraction.
This lets you write code that is a lot more self-documenting without having to resort to incredibly ugly things like Windows' Polish Notation warts.
>>1
Usually I use the 1st of your choices.
But if I have many related functions or procedures, then I use the 2nd way.
>>12
Contractions aren't cryptic. Ask any linguist. Ask any weeaboo, for that matter. I bet you Obj-C advocates use printf() without whining, too, unless you've caught the Java AIDS.
Generally people working with a program are familiar with the application programming interfaces (i.e. POSIX-y open(2), which has O_RDONLY and friends) and so something like the open_file above wouldn't be at all strange. Well, it might be on the first day on the job... but if that's a barrier then perhaps the guy ought to get the boot instead? Most of this stuff has manuals, you know.
The point I was making was that long names don't make things any easier to understand (if they did, then WOO HOO we could use those to paper over dumb coworkers!). A function called openFileOnTheFileSystemLikeWithArgumentsAndForReadingByName("name", ReadMode|ReadOnlyMode|ReallyNotForWritingMode) not only doesn't make anything more understandable, but also takes a whole lot more space on the screen, longer to read and (worse) longer to look up! Worse, when you try to use that function again, you'll likely need to look up the flag names for the second parameter, since they're written out like that and cannot be rememered as a simple O_RDONLY or some such.
Call frequency has nothing to do with it. Neither does describing the arguments. It's perfectly common for something that has to do with the filesystem (as hinted by the "file" bit, and the "open" bit) to take a name, which identifies the path to operate on, and a set of flags in an integer. It's what we call an idiom. It might be a bit "difficult" for those who had trouble understanding how an integer variable can be used as a 31-item set of boolean values, but seriously if one has trouble with that sort of thing then perhaps they should be in school studying the topic rather than employed and not putting something as fundamental as that into practice!
Every single function is not going to be an idiom. The vast majority aren't. Those are the point. Try not to get caught up on details.
I don't see why you say describing the arguments has nothing to do with "it", whatever "it" is, because in my example the whole point was to describe the arguments, so I would have thought that would have a lot to do with "it". Neither do I see your point about not understanding bit fields, because at no point did I suggest not using them. I just suggested that actually writing out the meaning of a constant is easier to understand that contracting it. Finally,
> Most of this stuff has manuals, you know.
The point was that if you can read the code without pausing to pick up the manual, that's easier for everyone involved. If you're going that way, you could just as well call every function a(), b(), c() and so on, and just document them somewhere else. That would save even more keystrokes.
My point is that as a very experienced programmer, I was at first somewhat put off by the verboseness of Objective-C, but after actually using it for a while, I've come to appreciate the self-documenting nature of the code one ends up writing. It would be a pain to write normally, but combined with autocompletion, it really works very well.
>>15
I think you need to go look up what an "idiom" is. A function is a function, and an idiom is an idiom.
Anonymous' opinion in this case is that reading code without pausing to look at the manual is a recipe for misunderstanding, if one skips over an important function call without taking time to think it over.
See my previous point about contractions. I'll give you that they're not a very good thing if they're not documented anywhere, or used willy nilly, however they aren't the pox some would have us believe either, nor are they something to be avoided at all costs.
I understand exactly what is meant by "idiom". Why do you think I do not?
>My point is that as a very experienced programmer, I was at first somewhat put off by the verboseness of Objective-C, but after actually using it for a while,
you've learnt to recognise obj-c's idioms.
Well, duh. And I think that they are better than those of other languages, which was my point.
From my perspective, option #2 is the way to go. The most important part of the function's, well, function, is that it provides an overview. The verbosity is secondary, and thus it makes more sense to place it in the subordinate position in the naming convention.
Further, if you organize your code alphabetically (a not uncommon practice), or even if you are viewing the members in an object viewer, you allow yourself to have functions like
otherfunction_simple()
otherfunction_detail()
which group together.