1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

#summary Log/Assert usage within Google Toolbox for Mac
=Log/Assert Usage w/in Google Toolbox for Mac=

==Terminology==

First, a little terminology authored/inspired by dmaclach:

*Log*

    A log is a debugging tool for reporting _interesting_ states to the developer running their code in a debugging mode. By interesting I mean states that the program can recover from, but doesn't necessarily expect. A log would be something that the implementor of the method feels is strange enough that it warrants notice by the developer, but not strange enough that the program cannot recover. As an example, several obj-c methods handle getting passed nil as a parameter. They don't generally expect nil, and will return an appropriate value (usually nil) but the fact that the client of the method is calling it with nil is probably a mistake, and something that should be avoided at a higher level. Logging is not a UI to report status back to the user, or a low-level way of communicating state to some other service. Logs can be turned on/off based on a compile time flag. Logs are purely a debugging tool, not a status reporting tool.

*Assert*

    An assert is something that a method requires to continue. If the assert fails, the function will (preferably) crash, or run in an undefined (most likely erroneous) state. The client calling the method has violated the contract with the method, and as such the method should not continue and has no recourse short of aborting. An assert fails in both debug and release mode. A perfectly valid implementation of an assert is to call log, and then abort.


*Reporting System/Logging System/Tracing System*

    Developers often want to keep track of what their application is doing, and will be quite application specific. These systems can be called "reporting", "logging" or "tracing" systems.  Exactly what they do/offer can be considered a _religious issue_ similar to exceptions vs error codes.  They may have levels and/or modules, support directing output to different sinks, and have runtime switches to control what is/isn't monitored.  In large applications, they have the ability to generate a lot of information.


==Log/Assert Withing GTM==

Now, what this means to GTM:

One of the goals with GTM is to provide a collection of code that developers can easily use without having to pick up stuff they don't need.  GTM uses {{{_GTMDevLog}}} and {{{_GTMDevAssert}}} as internal calls to provide logs and assertions; it is *_not_* meant to be a reporting system.  These two calls are meant to be _extremely_ simple.  If a developer does nothing, {{{_GTMDevAssert}}} will macro into {{{NSAssert}}} in all build styles. {{{_GTMDevLog}}} will macro to {{{NSLog}}} in _Debug_ builds and will macro out of the code in _Release_ builds.

GTM uses {{{_GTMDevLog}}}/{{{_GTMDevAssert}}} as described above, to log two classes of problems for developers.  No more, no less.  The intent that is any true errors that would need to be presented to an end user should be returned from APIs via {{{NSError}}} objects and/or other standard Cocoa practices.

GTM uses {{{_GTMDevLog}}}/{{{_GTMDevAssert}}} instead of directly calling {{{NSLog}}}/{{{NSAssert}}} to allow a developer using GTM to remap these messages into any reporting system _their_ application uses, by providing different definitions of these two macros in a project's prefix header.