Enabling easier debug

[johnarwe]

Breaking this question off from issue #19 into a separate discussion, since the initial response was not immediate consensus. Prior discussion from that issue copied here for the reader's convenience:

johnarwe:

@0tho , how would you feel about me adding one or more commands to toggle console.log calls for various "topics" (all defaulting to off)? In debugging the causes of these issues, I added "more than a few" such calls that could be grouped into logical units (one around lifecycle events that drive parsing, one around actual rule parsing, ...). I'm a tiny bit reluctant to just remove what I added, OTOH I certainly don't want npp to flood the log unless a human has consciously requested doing so. I'm thinking they'd only be accessible via the command palette, although I would not object if you wanted them hung off the Packages > npp entry as well.

otho:

Wouldn't many console.log pollute the code with no other reason to exist other than debugging?

[johnarwe]

I agree, it's rarely a trivial decision.

My thinking is:

• At some future point, when I suspect I'm on the trail of a new problem, or working on an enhancement, if there is some existing debug code that I can easily enable, then it's faster/easier for me to figure out what's going on and how to fix it (bug) or increase confidence that I have not regressed anything (enhancement).
• If I've been away from the code for long enough, I won't remember much about it. Someone learning the code new from scratch would be in much the same state. Having existing debug code in there at critical points should help them learn the code's intent (which is often more important than what it's "doing at the moment") more quickly.
• If I'm trying to help someone else using it debug odd behavior they're seeing, being able to quickly trigger some debug output makes the process faster and more reliable.
• As long as the debug output is disabled by default (which was my intent when I raised the question, in case that was unclear), the log won't be polluted with output unless a human consciously does something (like run a command that's either on zero menus, or is clearly labeled as a debug command).
• For new people trying to debug/enhance the code, even disabled-by-default logging statements serve as a form of internal documentation. It certainly wasn't trivial from reading the existing code how its panel "cache" works, for example.
• Async event-driven apps tend to be harder for humans to deal with; one false assumption about what's sync and your goose is cooked. Witness issue Project nav-marker-rules will typically not be used on activation #20, which is a just such a consequence. If you read that constructor, the simple (sync) reading means it should work fine. You have to remember (or have reality prove to you) that run-time execution order is completely different in order to see why there's a bug.

Generally, the longer I've needed to maintain the same code (sometimes: years), and the more code I inherited from others (especially if they're no longer around), the more I've wanted copious comments and/or debug output to help me "remember" things about the code I've forgotten since the last time I worked on it.

[johnarwe]

BTW, as a special case - and potentially one worth treating separately from the general question, although it's related - consider a new NPP user.

1. You install NPP for the first time, open some file(s). The file(s) you open happen to result in zero markers.
2. You embed (add) some #marker-rule lines in one of the open files. Again, zero markers.

Today, NPP gives that user no feedback of any kind in either case above (at least, none that I can find). Note that in case 1, atom-package-generator's default output is (now, at least ... not sure if this has changed over time) to log each call to toggle(); NPP never logs it. So even if they look at the dev tools, the user is unsure if NPP is just broken or is working but generating no output.

Case 2 is trickier, because the correct output depends on the user's intent. Taking the more likely case where the user intended the newly embedded rule to match at least one line, it doesn't and they have no idea why. "step 1" for them to resolve that is to read and understand "all" the NPP code... at least enough to know where to insert their own logging. It doesn't help that NPP itself silently runs certain transformations (like trim()) on the buffer lines, so even a completely valid regex that depends on leading whitespace will never match in NPP, even though the same regex run against the raw file would match.

Project-level rules is just another variant on case 2.

Both cases, in addition to the more general bullet list above, led me to wonder out loud if NPP didn't need some form of output. Since the "right" output varies considerably between case 1 and case 2, I started to think about a command (flag, setting perhaps) for each "fairly distinct" case. And that led me to "how do I do that without creating a confusing user experience" especially for other users that do get immediate feedback (because they opened "the right" file, i.e. one that led to >0 marks being populated).

The answers are not obvious, which is why I put out a feeler on things in the original issue.

[marcel0ll]

I agree that NPP should give a better feedback for users, and now I see that more logs will help people that are writing their own marker-rules.
Also I think NPP should always be open when active, even with 0 markers and maybe have a simple feedback message that no markers were found. (will create an issue just for this)