macOS Program Design and documentation using Key-Value coding

[gekko513]

I don't know any coding practices, model designs and documentation standards that address Key-Value coding properly, but maybe there is and I've missed it.

Standard UML lists members and methods but how do you handle the planning of possible keys for members that are dictionaries of key-value pairs?

.h files with method prototypes makes documenting the purpose and the way to use a class easy, with the exception of key-value based methods. Is there a recommended way and place to document the key-value behaviour of a class in the .h file?

Is there a best practice standard for documenting key-value properties when used with cocoa bindings?

 

[caveman_uk]

I presume you mean aside from the setter/getter methods a class may have?

 

[gekko513]

Yes, I mean if a class has a member for instance like this:

- (NSMutableDictionary*) properties;
- (void) setProperties:(NSMutableDictionary*)p;

 

[HiRez]

I don't think so. AFAIK the convention of stuffing a class's properties into a dictionary is not an Apple/NeXT one. I can't recall seeing it done that way in any official Apple code, I think they prefer the separate setter/getter methods.

 

[gekko513]

I don't think so. AFAIK the convention of stuffing a class's properties into a dictionary is not an Apple/NeXT one. I can't recall seeing it done that way in any official Apple code, I think they prefer the separate setter/getter methods.

Then what's NSUserDefaults?

 

[caveman_uk]

...or indeed the print system which relies on a dictionary (NSPrintInfo).

In short, to answer your question....I dunno. If you find an answer let me know (other than commenting a like hell in the .h file).

Other tricky questions...how do you document a .nib with a ton of bindings in it?

 

[gekko513]

Other tricky questions...how do you document a .nib with a ton of bindings in it?

Exactly ...

We didn't learn about these kinds of things in CS. That's why I'm asking.

Do the Cocoa programming books have anything to say about this? Have anyone here read them?

 

[caveman_uk]

Do the Cocoa programming books have anything to say about this? Have anyone here read them?

I've read them and the answer is no.

 

[HiRez]

Then what's NSUserDefaults?

NSUserDefaults and similar items are special cases, I'm talking about generic object property accessors. And I've never seen Apple do them with a dictionary, though I've seen it in a bunch of third-party code.

 

[gekko513]

NSUserDefaults and similar items are special cases, I'm talking about generic object property accessors. And I've never seen Apple do them with a dictionary, though I've seen it in a bunch of third-party code.

Apple uses NSDictionary for class attributes in NSOpenGLPixelFormat and NSAttributedString also.

I can't remember having seen Apple using mutable property dictionaries, though.

But there's a Cocoa Bindings tutorial over at CocoaDevCentral that can give some explaination why you see it in a bunch of third-party code.

That's the place I got the idea of using property dictionaries with cocoa bindings. It's very convenient, but I see some documentation and maintainability problems with the practice.

 

[Palad1]

Here's my coding practices when I'm using hashtables (c++ / c / c#):

If the number and content of the keys can be known at compile time, I usually stuff them in the class containing the hashtable.

If the number cannot be known, but the format is, I create a method that outputs a key. Here's a c# sample:

public class MyClass
{
 private m_Hash=new Dictionary<string,string>();

 /// <summary>
 /// Outputs a key for the dictionary 'id:epoch"
 /// <summary>
 public static string KeyForDictionary(int id, DateTime time){
   return string.Format("{0}:{1}",id,time.Ticks);
 }
///... lotsa code but I gotta go
}

cheers