Coding Tips

Jens Alfke has an article with a handful of coding tips. I agree with Jens in general, although I would quibble with or fine-tune a couple.

Prefix your instance-variable names

This is indeed a good practice, and I like Jens' insight that what this gives you is at-a-glance understanding of a variable's scope and lifespan. This wise practice is not followed much in the Java world, and is one of those long-standing, good OO programming lessons that Java has forgotten (among others such as "private instance variables get declared last").

Regarding "Hungarian Notation", this abomination hasn't been valid for nearly 20 years. It's always been ugly, and has been completely pointless in C++.

I use the "m" prefix in my C++ code, except when I'm working in a code base with an existing convention such as the "f" from legacy OP/MacApp-derived code, or the "_" convention in the Java code I work in at the office. I actually like "_".

I think it's also useful to prefix private and protected method names. "_" is used where I work. It's a shame that in ObjC this is "reserved" by Apple. The suggested idea in the Apple docs that you prefix all your private methods with your company's initials is insane, but I guess something like it is the only way to guarantee uniqueness in some of the crazier ObjC dynamic dispatch scenarios. Perhaps "__" is better. This is not an issue in C++ because no one can sneak in after the fact and insert base class methods that you are then accidentally overriding due to a name clash.

"TEMP" and "FIX" markers

This is a useful practice, but you really have to be careful. It is almost unavoidable that these markers will live longer than you intended. A "FIXME" that has been there for a year is a bad thing, and it will happen. If you can eradicate them before checkin or before final release as a rule, that's a good idea, but it may not be realistic.

As far as naming goes, I suggest using "todo" rather than "TEMP", "FIX", or "FIXME" (which I used to use) because "todo" is actually a supported convention in some Java IDEs such as IntelliJ IDEA, which actually has a window to show your todo list and provides syntax highlighting for todo's. Also, the word "temp" is too commonly used in actual code as a variable name, so it's not very searchable.

Your own special logging function.

Jens is on the right track here, but you don't need to roll your own, and you need to be careful about overhead while still keeping your logging code.

My Code Vault C++ framework came about before log4cpp was around, so I modeled the VLogger facility loosely on log4j (a widely used Java logging API). I suspect there's a log4oc out there if you are using Objective-C, but as with most ObjC-specific stuff I would generally recommend using C++ instead so you are not locked unnecessarily into ObjC (for non-Cocoa-UI-specific code) and unable to emit log output from your more portable C/C++ code. You may want to Google for "log4cpp", "log4oc", "log4objc", "log4Cocoa" before writing your own. :)

The idea with logging is that you should leave all of your logging code intact, and it should be configurable at runtime to obtain the level of detail that is needed. In a correctly behaving release environment, logging should only emit warnings and errors; but you should be able to turn up the log level externally to get informational or debug-level logging output. (This is different from information that is logged as a sort of audit trail or journaling mechanism where everything must be logged all the time.) One key to doing this is to make sure that you do not construct the detailed log output unless the level is enabled. Fortunately the C preprocessor, in all its badness, does help make this pretty easy, allowing you to define logging macros that check the log object's level before constructing the output, avoiding the overhead if nothing would be output.

For example, when I need to log message traffic, I use a macro that not only uses the correct logger, but also checks the level before constructing the hex dump data:

VLOGGER_MESSAGE_HEXDUMP("Inbound client message:", buffer, length);

If debug level logging is turned on for the message logger, the nicely formatted hex dump is created and logged. If not, then this macro only has the overhead of finding the message logger and checking its level. Furthermore, if the first argument's string has to be formatted (for example, in simpler logging macros where the string is the log output content), the preprocessor macro avoids the formatting of the string unless the specified log level is enabled.

Where I disagree with Jens on this topic is that you should not only leave your logging statements in the code rather than removing them, but in addition you should not be changing macros to disable logging in your final builds, but rather it should all be configurable; you will miss things otherwise, and you will not be able to enable more output at runtime in an already-deployed build. (The one exception might be logging statements that occur in very time-critical code where even the overhead of checking the log level is unacceptable.) This will depend on what it is you're building and how it gets delivered and deployed, but if you are building mission-critical server software, it's likely that you must have logging, and you must be able to adjust the logging level of an already deployed and running server, in order to diagnose problems that occur in the field. It may simply not be acceptable to bring down servers in order for you to install a brand new build in which you have made a compile-time change to how things are logged.

Zero tolerance for compiler warnings

Right on. "-Wall" is your friend in GCC. It's also very, very helpful to build with different compilers, since they are all picky about different things. If you are writing "plain old C++" code that *should* work on different platforms, you will weed out actual bugs if you try it on different platforms and compilers. Of course, when working on a large existing code base, or when using certain libraries' headers, you might not be able to apply this, at least not completely/easily/immediately.

Don't use tab characters in source files!

Jens is right. No question that many people disagree; I used to. I used to feel that tabs were unquestionably the way to go; all you had to do was agree on the indent level, or tell people how to set the indent level to whatever your programming standard defined. But somewhere along the line I read this essay by Jamie Zawinsky and it changed my mind. He is absolutely right. I had to admit that I was looking at it from the wrong angle. Tabs in files simply create an interoperability problem that cannot be consistently dealt with by the reader's configuration options because the reader doesn't know what the writer intended. Spaces avoid this problem from the start.

Set your text editor to indent using spaces, not using tabs. Anyone who ever opens your files will see them formatted exactly as you intended.