The number of zombies have been on the rise. Lately we have almost stopped their growth, however they are still great in numbers.
There has been built many great weapons to combat this, see Jack of All Trades, Master of None - Let's work together to offer ultimately better content, faster or Call of Duty II - We're still on a mission. The idea is somewhat controversial, and hence would like to start an discussion on the matter before doing something more drastic.
The new weapon: Documentation
Many users including myself spend time writing the same improvements to users over and over again, like violating the DRY principle. Giving references to the same documentation over and over again in itself also violates the DRY principle.Searching up links to documentation and coding-principles takes time, time that would (imho) be better spent on improving the posters code.
Similar to Frequently Posted Comments, such a post would serve as a reference list to common documentation and practices that you often suggest in your answers. My idea is to have one answer for each language, and one answer for general principles. Both of these should just be at maximum a few sentences "bombarded" with links for further reading. They would then be followed by code snippets and your own hand-tailored suggestions.
What it is and what it is not.
Similar attempts have been tried before, see Create a reference for newbie common mistakes or 'Canonical' questions to help address common issues. However this is different as it is not meant to be used by beginners, but by us.
The idea is NOT to create copy-and-paste answers to questions and every principle and bit used should be paired with examples from the actual question. Nor is it an attempt to create less handcrafted answers, but more. Ideally when one spends less time writing about the general principles to follow, one can spend more time focusing on the deeper problems with the code, or new ways to improve it.
@Phrancis showed an example he often encountered in SQL
Your table aliases are not helpful. Single-letter aliases give no information at all about what they are referencing. It's fine for aliases to be short, as long as they carry some form of useful meaning. For instance, [start critiquing the specifics of OP code]
While a comment that would be placed in the general principles section might sound like this:
Your main method is responsible for too many things. The main method is meant to be an entry point into your program, rather than the program itself. As a general principle try to let each function serve a single purpose ([Single responsibility principle](https://en.wikipedia.org/wiki/Single_responsibility_principle)). It would be better to extract some of the code into [routines/methods/functions/classes and continue with OP code and examples]
Ideally though they should be a tad shorter. Another language specific snippet I see again and again is the
quit() function in Python. The function is very natural for a beginner to try to use, however as documentation shows, in most cases it can and should be avoided.
A bad example would be linking just to PEP8 as it would be too general and not really give the OP much of anything. Instead the ideal solution would be to leave a short sentence explaining what PEP8 is and then add more concrete examples where OP fails to follow these principles. Is the naming convention unclear, is the indentation wrong, is the spacing between statements inconsistent, and so forth.
Some attempts at such a thread have been tried earlier. Python - Common Improvements, however it was closed for being unclear. I hope I have made myself clear with what this questions and answers try to achieve.
After a bit of discussion in chat this is a very controversial topic. Some say that this would decrease the hot-fuzzy-feeling of receiving a hand-crafted review. While I would think the opposite, that it would increase the handcrafted parts, as less time is spent looking for documentation.
- Could and should such a weapon be added to our arsenal?
- Would this diminish the feeling of our fuzzy-warm personalized answers?
- Could it streamline the process of writing answers for beginner level questions?