“Don’t: Document log messages unless required for QA and testing”
The above implicitly requires that ALL log messages that would be used to by QA or by PTL tests needs to be documented.
I think this is unnecessary, and is even a severe overhead. We do not document internal interfaces in the design document. Code and tests will anyway be updated by the Pull request before they can be merged in.
I suggest we modify that statement to say something like:
“Don’t: Document log messages unless explicitly needed to be added to end user documentation”
I also agree with Subhasis. Log messages are more for support and debugging and don’t really count as “design changes” in my mind. Accounting logs are kind of special as they are a supported interface to obtain accounting/statistical information, so if there’s a change in accounting logs, that does need to be documented, but all other log messages don’t really need to.
I second @subhasisb on this. Unless the log message being introduced or being changed is an accounting log or something which gets displayed in say tracejob I would recommend not to put them in EDD.
If you’re adding new log messages (or even changing old ones), then I think it should be documented somewhere that’s not in the code. Maybe in a source code guide?
I understand that some logs are not supported and can be changed at any time, but since we use those for testing things in pbs_benchpress, I don’t want to be grepping through the code.
I agree that the DDs are not the place to put them, but I think they need to go somewhere.
PTL tests are synced with a particular branch/codeline of PBS, and in essence is part of the PBS source code. Since PTL is part of PBS source, my perspective is that log messages used by PTL are like internal interfaces. If there is a mismatch between tests and log messages, tests will fail. We would not need to grep for them. So I can’t see a reason to document them anywhere for the purpose of PTL.
Practically too, by the time one has documented a log message in any document, chances are the log message has changed in code…
I think that in nearly all cases log messages should be self-documenting. By that I mean if the log message is not clear and concise, it probably shouldn’t be there to begin with. There are some cases where the context in which a message is issued could affect its meaning. In those cases, adding a comment in the code will help others understand both the necessity for and the meaning of the message.