Nomenclature

A standardized, consistent nomenclature is important for software development. The names need to be clear, unambiquous, and predictable. This is all just a part of helping prevent the addition of more complexity to your project. The following are my own choices as they have evolved up to this point. Please feel free to suggest alternatives that you can think of.

  • Every logging-output method has a name that begins with the verb "Log", as in "LogWarning" or "LogError" (other than the separate set of methods that are provided to implement the ILog interface). Thus when Intellisense is showing you all of the possible methods, the logging methods are grouped together.
  • Each distinct output from a logger is called a "log-record". It was tempting to use "log event" but that would create instant confusion.
  • The rendition of a log-record within a viewer is termed a "trace".
  • That portion of a trace that includes the (optional) contextual information (time, host, etc.) is a "prefix".
  • The "Windows Event Log", is always called exactly that within this code or documentation - never shortened. Since this is a logging library, references to a "windows log" or "event log" would be confusing.
  • That portion of a log-record or trace other than the prefix, is called the log "message".
  • The log-records always have an assigned LogRecordLevel, which may be referred to as it's "record-level".
  • Your program that you are writing or maintaining, which makes calls to LogNut to do it's logging, is referred to within the LogNut API as the "subject-program". This is important since there are many programs that could apply during a given conversation.
  • The computer that your subject-program is running on, is called the "source-host".
  • When you are viewing your graphical user interface (GUI) within Blend, or within Cider (the visual design surface in Visual Studio) - we refer to this as "design-mode". This clarification is essential because these tools actually execute some (but not all) of your code in order to render the XAML visually, thus we have the property "IsInDesignMode".
  • GUI control names use the standard prefix notation (e.g., ckbx for CheckBox) plus the actual name of the API property they control (e.g., ckbxIsShowingPrefix). This lets you easily find which GUI control controls what property, and helps remember the property syntax.
  • Boolean-valued properties are named starting with "Is" unless the syntax compells an alternative prefix.
  • The term "target platform" can implicate two distinct meanings in the context of this library. One: the host environment upon which the LogNut DLL or its' utilities can execute, and Two: the host environment (including set of tools) upon which the LogNut projects themselves may be compiled and built. To distinguish the two, the phrases execution-platform and development-platform are used.

Last edited Nov 26, 2012 at 10:29 PM by JamesHurst, version 9

Comments

No comments yet.