Re: Coding norms
Re: Coding norms
- Subject: Re: Coding norms
- From: Mike Ferris <email@hidden>
- Date: Thu, 12 Dec 2002 09:37:13 -0800
1. Is it customary to declare delegate methods that a delegate class is
going to implement? For example, if you have an AppController class,
although it is not necessary to declare applicationDidFinishLaunching
in the
header, but is it customary to do so?
For Cocoa itself, the general rule of thumb is that you declare public
methods. You declare overrides of public methods if the override does
something worth documenting (eg it changes the semantic of the method,
or does interesting extra stuff that folks need to know about). The
same rule might be applied for delegate messages as for overrides. But
one thing to keep in mind is that the delegate methods are public API
and a subclasser of your class may need to know that you've implemented
a delegate method so they can know to call super if they need to
implement it themselves in a subclass.
Stated more simply, the rule of thumb in Cocoa is to declare methods
that ought to be documented.
This is not completely strictly adhered to in the frameworks... but it
is the rule of thumb.
2. What do most people (or perhaps what does industry expect) in
regards to
private methods? For example, a method that is only used internally
by a
class can be simply defined at the top of the implementation file and
not
even declared in the header. What is the norm? Is there one?
Personal
preference?
If the API is truly only going to be used within one file, declaring it
at the top of that file is not a bad way to go.
Beyond that, it is easy to get carried away with levels of visibility
of headers. There's at least four levels I can think of that come up
in largish projects:
Public
Private
Project
Internal
Public headers go in the Headers folder of the framework and are there
for any client to use. Public API should get the most attention and
making something public generally commits you to supporting it forever
if you don't want a lot of ticked off clients on your hands.
Private headers go in the PrivateHeaders folder of the framework and
are generally available for folks throughout the organization to use
(typically the organization that produced the framework). Typically
the PrivateHeaders of a framework are not shipped external to your
organization. Even so, these headers may be used by folks outside your
immediate group and therefore removing or changing private API will
probably require some advance work to identify internal clients and
make sure they stop using the API before it disappears or changes.
Project headers do not get installed in the built framework. They are
available (by convention) to any implementation within the framework.
For example, if NSMenu had "project" API, NSWindow could use it. No
clients outside the framework itself are allowed though.
Internal headers do not get installed in the built framework. They are
only for use by the subsystem that defines them. Maybe NSMenu has some
internal API and it is OK for NSMenuItem to use it, but not unrelated
things like NSWindow.
The distinction between Internal and Project is often not needed,
especially for smaller projects, and even most of the time for large
projects.
When I have used these various levels of visibility in the past I have
used a naming convention like:
NSMenu.h
NSMenu_Private.h
NSMenu_Project.h
NSMenu_Internal.h
At the very least, if you're developing a framework you should keep two
levels of visibility: Public and everything else. That's the boundary
that really matters and where unwise choices will come back to haunt
you forever. Add in further distinctions such as the above if you have
a need for them.
Mike
_______________________________________________
cocoa-dev mailing list | email@hidden
Help/Unsubscribe/Archives:
http://www.lists.apple.com/mailman/listinfo/cocoa-dev
Do not post admin requests to the list. They will be ignored.
| References: | |
| | >Coding norms (From: Alan Nilsson <email@hidden>) |