VTK/MinimalExample: Difference between revisions

From KitwarePublic
< VTK
Jump to navigationJump to search
No edit summary
mNo edit summary
Line 2: Line 2:


# ''Entice the readers to help you with your question.''  
# ''Entice the readers to help you with your question.''  
 
#: If you don't as the question in an engaging way, This means you should provide as much detail as you can about your situation. This includes things such as your operating system, compiler version, etc. It should also include details about the steps you have taken to try to solve the problem already (read XYZ documentation page, tried XYZ example, etc).
If you don't as the question in an engaging way, This means you should provide as much detail as you can about your situation. This includes things such as your operating system, compiler version, etc. It should also include details about the steps you have taken to try to solve the problem already (read XYZ documentation page, tried XYZ example, etc).
 
# ''Ask your question in a way that will benefit future users.''
# ''Ask your question in a way that will benefit future users.''
 
#: Again, this is driving at getting people to help you. Odds are, if someone recognizes an opportunity to answer a question that has not been answered before and can be preserved for future readers, they will be much more willing to spend time on it.
Again, this is driving at getting people to help you. Odds are, if someone recognizes an opportunity to answer a question that has not been answered before and can be preserved for future readers, they will be much more willing to spend time on it.
 
# ''Most importantly, you should provide a minimal, compilable, self-contained example of the problem.''
# ''Most importantly, you should provide a minimal, compilable, self-contained example of the problem.''
 
#: This part is critical, so we elaborate in great detail below about what makes a good example.
This part is critical, so we elaborate in great detail below about what makes a good example.


==Minimal==
==Minimal==

Revision as of 02:09, 8 September 2012

When asking questions on the mailing list, there are several goals which must all be met to extract the maximum benefit from the efforts of everyone involved. Please take careful note of the following points, as they are key to producing a "win-win" situation. By asking a question that follows the guidelines on this page, you are not only helping the community (which is your primary goal, right? :) ), but you are also greatly improving the chances of getting your question answered so you can go about the business that you were working on before you came across the problem.

  1. Entice the readers to help you with your question.
    If you don't as the question in an engaging way, This means you should provide as much detail as you can about your situation. This includes things such as your operating system, compiler version, etc. It should also include details about the steps you have taken to try to solve the problem already (read XYZ documentation page, tried XYZ example, etc).
  2. Ask your question in a way that will benefit future users.
    Again, this is driving at getting people to help you. Odds are, if someone recognizes an opportunity to answer a question that has not been answered before and can be preserved for future readers, they will be much more willing to spend time on it.
  3. Most importantly, you should provide a minimal, compilable, self-contained example of the problem.
    This part is critical, so we elaborate in great detail below about what makes a good example.

Minimal

Do not include code that is not relevant to the problem. For example, if you are having a problem getting the neighbor of a cell that you click on (in the click event of an InteractorStyle), and getting to that point is not involved in the problem, then you should make the example specify the cell that you want to get the neighbor of programmatically, without involving any interaction or visualization.

Compilable

Do not send code like this:

<source lang="cpp"> polydata = sphereSource->GetOutput(); </source>

instead, make sure that readers can copy+paste+compile:

<source lang="cpp">

  1. include <vtkPolyData.h>
  2. include <vtkSphereSource.h>
  3. include <vtkSmartPointer.h>

int main() {

 vtkSmartPointer<vtkSphereSource> sphereSource = vtkSmartPointer<vtkSphereSource>::New();
 sphereSource->Update();
 vtkPolyData* polydata;
 polydata = filter->GetOutput();
 return 0;

} </source>

Self-contained

Unless the problem is "I am having trouble reading this file", do not include external files in your examples. That is, rather than use a vtkXMLPolyDataReader, use a vtkSphereSource. Rather than read a text file with parameters, or accept command line parameters, hard code them into the example. Again, Copy+Paste+Compile is what makes life easy for the readers, and hence will get you an answer with higher probability.

Other notes

Formatting/indention:

Please recognize that the mailing list is a "plain text" environment. When you post code, realize that it may be read in an "80 character column" reader. Please ensure your tabs, indentation and line breaks look sensible. That is, rather than:

<source lang="cpp"> ...

                       writer->Write();
                       }else{
                               std::cout << "file exists." << std::endl;
                           ofstream fichier ("file.xyz",ios::out | ios::app);
                                       if(fichier)  // if the opening was successful
                                       {
                                                   cerr << " the opening was successful!" << endl;
                                       *//     now here i want the code that makes me save the "combined" in

"file.xyz" without overwrite the existing* ... </source>

post: <source lang="cpp"> ...

 writer->Write();
 }else{
 std::cout << "file exists." << std::endl;
 ofstream fichier ("file.xyz",ios::out | ios::app);
 if(fichier)  // if the opening was successful
 {
   cerr << " the opening was successful!" << endl;
   // now here i want the code that makes me save the "combined" in
   // "file.xyz" without overwrite the existing*

... </source>

The more readable you can make the example, the more likely you are to get a quick response (or a response at all!).