Re: Balancing Logging and Code Readability

How to keep the logging from swamping out your code logic is a good question.

One thing I would suggest is that info and debug level logging can replace comments. Just like code, there is no sense duplicating non-code either.

As for the warn and error levels, testing for those cases could mostly be done at the beginning of a function, while you're gathering and validating parameters. Rather than putting a log message in the center of a function where it makes a call, try to move the logging into the function being called. The function was probably written to keep things clear and avoid duplication of code, so you might as well use it to avoid duplication of logging commands too.

If you can keep the conditional logging confined to the beginning/end and thus out of the logic, and then replace one line comments with one line debug/info logging, the code should stay clean. The trick would be learning to read debug-info logging as if it were a comment. Perhaps by adding a rule to the code highlighting in your editor.

- SJ

How to make perldoc.perl.org resizable too!

Comment on Re: Balancing Logging and Code Readability

Replies are listed 'Best First'.
Re^2: Balancing Logging and Code Readability by saberworks (Curate) on Sep 14, 2009 at 17:24 UTC
I've had the same problem as the OP and the idea of adding a syntax rule to recognize log lines and highlight them as comments crossed my mind as well. Then I remembered I saw a perl module on CPAN once that allowed you to write comments in a special way that would be logged. I can't seem to find it after ~10 minutes of searching but it did look interesting so if this rings a bell for someone else, please post a follow-up.	[reply]
Re^3: Balancing Logging and Code Readability by BrowserUk (Patriarch) on Sep 14, 2009 at 17:36 UTC
Smart::Comments or Devel::StealthDebug? Examine what is said, not who speaks -- Silence betokens consent -- Love the truth but pardon error. "Science is about questioning the status quo. Questioning authority". In the absence of evidence, opinion is indistinguishable from prejudice. RIP PCW It is as I've been saying!(Audio until 20090817)	[reply]
Re^4: Balancing Logging and Code Readability by saberworks (Curate) on Sep 14, 2009 at 18:41 UTC
Ah, yes, Smart::Comments is the one I remember seeing. Looks like a cool module and may help the OP. However, there are quite a few bugs open and no new release in a year and a half, so that may be something to consider.	[reply]
Re^5: Balancing Logging and Code Readability by BrowserUk (Patriarch) on Sep 14, 2009 at 19:04 UTC
Re^6: Balancing Logging and Code Readability by ack (Deacon) on Sep 17, 2009 at 02:11 UTC
Re^5: Balancing Logging and Code Readability by ack (Deacon) on Sep 17, 2009 at 02:08 UTC
Re^3: Balancing Logging and Code Readability by dinomite (Sexton) on Sep 15, 2009 at 05:01 UTC
Since you're already using Log::Log4perl, you might check out it's built-in `:resurrect` tag or the similar functionality provided by Filter::Log4perl.	[reply] [d/l]
Re^4: Balancing Logging and Code Readability by ack (Deacon) on Sep 17, 2009 at 02:16 UTC
I have seen the `:resurrect` tag but haven't really looked into it. The quick glance that I gave it didn't really connect in my mind that it might be helpful to my dilema. I hadn't seen the Filter::Log4perl module, so I'll definitely look into it. Thanks for the suggestions. I'll look into them. ack Albuquerque, NM	[reply] [d/l]
Re^2: Balancing Logging and Code Readability by ack (Deacon) on Sep 17, 2009 at 02:06 UTC
Wow! Excellent suggestions and some interesting strategies that I hadn't ever thought of. One thing I would suggest is that info and debug level logging can replace comments. Just like code, there is no sense duplicating non-code either. That is something that had never occured to me. I really like that. It will take some getting used to, however. I tend do copious commenting and have found that, to some extent, the commenting (as with the logging) can easily get in the way of viewing the actual code logic and flows. The idea of using logging as an alternative to commenting sounds really powerful and offers the opportunity to "kill two birds with one stone" as they say. As for the warn and error levels, testing for those cases could mostly be done at the beginning of a function, while you're gathering and validating parameters. Again, a great suggestion. I will work on that. Rather than putting a log message in the center of a function where it makes a call, try to move the logging into the function being called. The function was probably written to keep things clear and avoid duplication of code, so you might as well use it to avoid duplication of logging commands too. So true and an excellent observation and strategy. The trick would be learning to read debug-info logging as if it were a comment. Perhaps by adding a rule to the code highlighting in your editor. I agree; it is something I'll have to work on. One thing that your suggestions leave me curious about is sort of highlighted by that last comment (re: "...learning to read debug-info as if it were a comment..."). Does that bode poorly for maintainability of code by others? That is, does that tend to make the code less accessible to others who may not have developed the facility of reading debug-info as comments? Just curious. Thanks so much for the great ideas and suggestions. I really appreciate it. ack Albuquerque, NM	[reply]