No Exclamation Please

In my current project, I've seen log lines like:

1Logger.warn("No null allowed here !!!");

Or the "I really stand out" tricks like:

1Logger.debug("->->->-> Reached this line !");

Writing log entries like this really show your inability to use your IDE for setting breakpoints and stepping through code,  while also showing your poor comunication skills. If I encounter these kind of log entries, I try to see if I can improve them, and/or adjust their level. Here are some pointers I use for writing log entries:

• Be informative. Try to include all information in the log entry which could help the reader determine the reason or cause for this log entry.
• Use full sentences. Write your log entries like a novel. It will make them easier to read, and will also allow system administrators to litteraly copy/paste the text into a mail when sharing information about problem analysis. They will thank you for it.
• Refrain from using "search strings". Lots of stars, dashes or quotes do not improve readability of the log file, and it will make it look unprofessional. Searching for a bunch of stars is just as fast as searching for a word, given the right tools.
• Don't overdo it. Try to have at most 1 log statement per method. Don't spoil it on trivial information, it will devaluate the rest of the entries in the logfile.

Using these guidelines, the log entries I showed you could be rewritten as:

1Logger.warn(
2	"The method 'storeUser' doesn't accept 'null' as it's parameter.");

and

1Logger.debug(
2	"The user with id "+user.getId()+" was stored in the database.");

Comparing these new versions with the earlier examples, I think you will find that there is much more information in these, and you can now even guess that these entries are from a storage method in a DAO for storing users.

Another important thing to think about when writing log entries is the level at which you log. For Log4J log messages, I use the following definitions to choose log levels:

• FATAL - The system has encountered such a severe error that it needs to shut down completely. No user can access the system after this log message. "Core dump" and "Crash" come to mind.
• ERROR - A serious error prevented the action from completing. Although the application is still running, the user session is probably terminated or in an awkward state. Examples of ERROR are temporarily inaccessable databases or remote systems which prevent the current action from completing succesfuly. A few error messages should be enough to call second level support in the middle of the night.
• WARN - The user session is still usable, and the system encountered an abnormality which should possibly be analyzed by a system administrator or level 1 support guy to see if corrective actions need to be planned.
• INFO - Info to the system administrator about interesting events. These events are "The application started up and is now ready for use" or "The application will use server XYZ for database access". Informative or confirmative messages.
• DEBUG - Everything else. Stuff you don't really need to see in a production environment. In some rare cases, you can set the visibility of the log levels to "debug" in a production environment if you have a really strange problem and are willing to sacrifice some system speed and storage to analyze. System administrators will (should) not want to see this information.

The last tip I am going to give you, which does not only apply to coding, but also writing mails and documentation in general:

Exclamation marks are a poor mans way of expressing the inability to indicate the importance of a sentence, while at the same time insulting the reader. Why do you assume that the reader does not get the importance of your words?

If you ever wonder why I didn't answer your mail immediately, see if there are exclamation marks in there. And no, adding some will not help.