No Exclamation Please

Some developers nowadays still think that putting an exclamation mark in their log entries adds to the visibility of their entry. When other developers notice this, they will add even more exclamation marks so their log entries are even more visible. I compiled a few examples of bad log entries and some pointers for you to improve your log entries.

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

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

Or the “I really stand out” tricks like:

Logger.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:

Logger.warn(
  "The method 'storeUser' doesn't accept 'null' as it's parameter.");
and
Logger.debug(
  "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:

Never, ever use exclamation marks in professional texts!

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.

Advertisements

8 Responses to No Exclamation Please

  1. Joris says:

    Hahaha Guus, nice exclamation marks!!!!

    Very valid points. One addition: never ever log something along the lines of “This should not happen.”.
    A.) We know, because that’s why it’s an exception, and
    B.) if it shouldn’t happen, you should have prevented it. 🙂

  2. Hugo says:

    YOU CONVINCED ME, I WILL NOT USE ANY EXCLAMATION MARKS IN MY TEXTS ANY MORE.

  3. rolfje says:

    Hugo is in the “advanced class”, and found a workaround for the exclamation marks rule. Either that, or he is using a hippie/vintage 75 baud terminal from the 1930’s.

  4. Hugo says:

    Next week post: No smileys please

  5. Joris says:

    🙂 🙂 🙂 !!!!!!!1!!one!!!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s