Table of Contents
What is a stub and why do you need one
A stub is a short piece of text that summarizes an idea. It is used in many different ways. In books, they are typically called “chapter summaries” or “summary chapters”. For instance, you might use a stub to summarize an event that takes place over several chapters (you could also use a summary chapter). Stubs are also useful in case of emergencies, where the author needs to pass on information quickly and clearly. In a technical document, they are an advanced form of a template. For instance, if you have to describe the same thing in a different way, you could create a stub and then write your text in that context.
The purpose of a stub is for the reader to get the basic idea quickly. Stubs are not meant for detailed explanations, so don’t go too in depth if you want to summarize something. A good rule of thumb is to keep your information short and simple. For instance, if you need to explain an important event that took a lot of time in the text, create a summary chapter instead.
How to write a stub
A stub can be written in several different ways. You can write a simple summary and then edit the text to make corrections. Or you can write a full-fledged document that summarizes the entire book or article. The most important thing is to make sure that the stub is useful.
There is no rule for how to write a stub. It’s important to select the appropriate method after you have read the material for which you are writing a stub. A misleading stub won’t help learning your subject and won’t save time later when you need it.
The links below are examples of stubs. These can be used as a guideline when writing your own. The stubs have been written by Wikibooks contributors and are meant to serve only as guides.
“Python stub” : “How to write a stub”
Category:Help Wanted contains more articles about these kinds of articles, that need writing.
===How to write a stub===
You want to mention something about the topic. That’s simple: start with “Here are some things…”, and then make your points.
Stubbing out dependencies
When writing a stub, it is often necessary to provide additional information. But of course you may not know all the details yet. In such cases, you should at least specify what information is missing and tell the reader where he can find those details. A stub that does not at least do this is likely to be worthless.
##
Title:Avoid making the assumption that stubs are readable
[“Stubs are intended to be read. If the reader cannot understand them, then there is something wrong with your design.”]
Unlike real code, stubs have no comments, they do not use docstrings, they have no tests. They are by definition thrown away. If you assume that a reader must understand all your stubbed values and you do not fill in the gap yourself, then you are making a serious mistake.
##
Title:Avoid making the assumption that stubs are readable”
[“Stubs are intended to be read. If the reader cannot understand them, then there is something wrong with your design.”]
Unlike real code, stubs have no comments, they do not use docstrings, they have no tests. They are by definition thrown away. If you assume that a reader must understand all your stubbed values and you do not fill in the gap yourself, then you are making a serious mistake.
##
Title:Teach people how to use your API, not how to use your stubs
Testing your stubs
You may find that a stub does not quite fit your needs. That’s okay. It can be modified to make it more useful. You don’t want your stub to be bad. It should serve as a guide for the rest of the writing process. When you’re finished with a stub, you may wish to use it as a basis for the creation of additional documents. You may also need a few examples of tests for different kinds of code.
Here are the examples below:
def test_function(self): # Gives a sample test case for the function. def test_method(self): # Gives a sample test case for the method. def test_class(self): # Gives a sample test case for the class.
##
Title: Testing your stubs
Article background information [to use as knowledge, not to be copied verbatim]:”python mock” : “What is a mock?” . “Python mock” : “Testing your mock objects”
##
Title: Testing your stubs
Best practices for stubbing out your codebase
Stubs are commonly used to document code. Whenever you are writing a function, web page or API, it is extremely helpful to write a stub that can be used as a placeholder and will then be replaced by the actual code at a later date. A “stub” is usually just one or two pages long, with all references to functions, properties and other items blanked out. This is important because it allows you to work on the interfaces without worrying about potential changes that might make them unusable or difficult to use. The stub can then be validated before the actual code is added.
In this article, I’m going to review some of the common problems you might have when stubbing out your code for testing purposes and how you can avoid them.
I’ll start by talking about how you should write your stubs. Then I’ll discuss how you should handle exceptions thrown from your stub. Finally, I’ll go into more detail about tests and the Painless auditing tool.
How should I write my stubs?
