: Re: What are the benefits of including complete working code samples in documentation When documenting software API so others know how to access the various methods, what data structures are used

@Goswami879

Vote Up Vote Down

There are different types of examples and they serve different purposes.

One type is the quick-start example that this answer describes: a complete, but small, runnable example packaged in a form that the users can easily use. "Hello world" is sometimes too simple (simplistic), but this example should use defaults where possible and not bite off too much -- the user should be able to run it and understand what he's looking at without too much research. This example generally shouldn't be code in <pre> blocks that people have to cut and paste; attach or post the code, project files, data files, or whatever's needed alongside the doc instead.

Another type is the focused excerpt, such as you find in API reference documentation. On the reference page about a class and its member functions, you include example invocations of those member functions in isolation. On the reference page about an interface that the user will implement, you include example implementations of key functions. These examples are not complete and runnable; you use them to demonstrate specific, focused points. This approach isn't limited to API reference pages; on my current project we excerpt published examples in the programming guides, too.

Another type is the full, realistic example. (Or sometimes a reference implementation.) . As with the quick-start example, you post this code separately rather than embedding it into the documentation text (which would definitely be bloat). However, in the documentation you can provide an overview of this example -- structure, descriptions of key components, flow diagrams, class hierarchies, or whatever types of explanation make sense in your specific domain.

Complete examples, whether quick-start or fuller, should contain good internal comments that focus on why and how, not just what. You're writing a sort of tutorial in the comments. Your comment-to-code ratio will probably be higher than in internal code, but it needn't be that much higher. Your goal is concise yet informative.

(0)

Login to post a comment!