Progether/IRC-Bot — pull request #41 by projectdelphai (2013-11-23 08:27:36+00:00)
Title: large rewrite of helper addon to reduce amount of code,text,and flooding

I realize this is a large commit (which is why I'm making it a pull request) and that it may be very controversial.

I want to explain my reasoning behind the changes and why I think this should be merged:

1. The help file I felt was way to big. Coming in a 361 LOC, it easily outweighed all the other addons just to give information to the user. This commit has 177 pure deletions (including the readme's 33) and removes 144 lines of code from help.py. This large subtraction in code without a large detraction in quality makes it worth it.
1. There was a lot of short/long description which I felt duplicated each other to much. It is easier to just combine the two into a concise description that gives the necessary information.
1. Seeing as the helper addon is there to provide users with the information needed to interact as quickly as possible, a lot of the text is too long and can be easily dropped for a short 'no description', 'no commands' etc.
1. A lot of the String constants are actually only used once and so can be placed in their respective positions without detracting from the flow of the code.
1. According to python PEP8, 2 blank lines between groups of functions and one blank line between regular functions. Takes away at least 10-20 lines.
1. Even if the flood problem is solved, progether is being used too much to keep talking in the channel; it's starting to become spam. And notice is handled differently depending on the client, code, and person, so it isn't static enough (and can be confusing for people new to irc). It would be better to have it all be handled in privmsgs where it is clear that a separate conversation is happening between the bot and the user.
1. Along the same lines of removing speaking in channels, any speaking functions should go in ircHelpers. A simple iterator in privmsgs and you can pretty much remove all speaking functions in help.py.

These were the main reasons that I reworked the help.py and I think that it would be worth it to merge this pull request because it decreases complexity, lowers potential spam, and makes it easier for new contributors to enter the codebase.

I did have other ideas for changing the helper.py, but felt that I had reached a sufficient spot to make a pull request. The ideas laid out below are for future commits if this is merged:

1. combine addon title, description and commands into one line. This would drastically lower the posts made by the bot and can be handled with the shorter texts. No way, it would grow to the line limit.
1. remove aid button. One doesn't really need to offer aid to someone else as a command. You can just tell that person to run !!help mail. The amount of code needed to give him/her !!help mail vs. the effort of just telling the person to run the command is disproportional.
1. convert addon description and meta-information from lists to string. It seems unnecessary to have them as a list if there is only one element in said list. I don't know if there is a reason for this or not.
1. removing all the debug lines. It takes up space and may never be used seeing as all the code works. If one needs to debug something, then he/she can just add in the print line. If debug is false by default, then it doesn't log anything and if it's true be default than really only I can see the logs in heroku which is useless to everyone else.

This is all that I can think of right now to explain my thinking. Please review the code and get back to me about what you all think. I think this is a good change to the code, yet big enough that I shouldn't just merge it (especially seeing as a lot of the code isn't mine). I would appreciate all thoughts.