johlju
commented
5 years ago Awesome that you put this together.
TL;DR: I like the idea, but I'm not sure this is something that would help us. It would be hard to enforce this. ant would just over complicate things for contributors and maintainers. 🤔 The reason for this number in the first place is to be able to correlate a localized string from a verbose/error where the log is in another language. You could then see the number, look for the number in the English string resource file, and there see the localized string key, and search for that key in the code.
Possibly group verbose messages together when possible (i'll show example)
I like the idea, but I think this will be hard to enforce, and complicate things for contributors where the style guideline is already a problem. It would also be hard to write a common unit test (in the test framework) to verify that the localized string has the correct number. It's easier to write a common test to verify that each string do have a number, and not a specific number.
I think you suggestion is gonne be overly complicated, and I think we should be able to reuse any localized string in a resource if it fits.
Start each function with a verbose message saying what you are going to do
I try to do that in the code I write. I think this is the normal (?) in most resource, but there are probably exceptions. Most older resource can be missing this because verbose message was not as important back then when the resource was created (focus on functionality, not the help that verbose message gives when users ask for help).
Verbose messages when comparing all parameters (state if parameter is in state or not) On Test, verbose message if state is compliant or not (maybe redundant?
These messages can also be from a helper function in another module, for example the new pattern i made when i refactored xADComputer.
If that pattern works, we should move it here as a common pattern and replaces or exist beside the common helper function Test-DscParameterState.
https://github.com/PowerShell/xActiveDirectory/blob/f91d0f3073c7bd5086bff31d27d87162ab1f0609/DSCResources/MSFT_xADCommon/MSFT_xADCommon.psm1#L1098-L1118
Verbose message for every try/catch?
Up to the contributor if it is necessary. I think it's normal to have a verbose message before or after an action/event (maybe both for long running tasks). We should not use verbose messages as debug messages. Verbose message can be used to see which actions was made or not made before an error was thrown, if the user can provide the verbose log. Normally the error message should be descriptive enough. But there are scenarios where I had needed the verbose messages to realizes the code went into the wrong code path because of values in either the desired state or the current state. In these scenarios I saw that the actions (verbose messages) that was made didn't seem correct.
kungfoome
related to #17
I had a few ideas about logging.
Example for 1:
I'll try and explain. So it's kind of a rudimentary way to trace the code. Messages that can be used throughout start with {n}000, this gives you about 3000 messages basically. I'll explain later.
All messages that come from Get start with 0100 All messages that come from Test start with 0200 All messages that come from Set start with 0300
If it's a message that is shared, it would be whatever number each function starts with. So Get is 1, Test is 2, Set is 3. So if a shared message is called within Get, it would be 100x where x is whatever the actual message code is.
In this example, I have 9000+ has any other messages per function. so if i were to add more messaging for a new function I may want to do 9100. Giving me a possible 100 messages per function. This can really be whatever you want it to after 0300 though. And 1000-3999 would be reserved.
Few examples of what it would look like: You can see here, It's called from Test -> Compare -> Get
Another longer one with parameter comparison:
Anyway, just some thoughts which may be helpful.