How to write documentation during programming

Question

You have the habit of coding, writing documentation, and making sure that they are in sync.

How can you achieve that? What are you recording? logical function? Concept? Or other best practices? Thanks in advance!

Answer 1

I am a python programmer and I write a lot of doctests , which is a python module that allows you to write tests as examples of a function using each function in the documentation line. Take a look at an example from here :

def factorial(n): """Return the factorial of n, an exact integer >= 0. If the result is small enough to fit in an int, return an int. Else return a long. >>> [factorial(n) for n in range(6)] [1, 1, 2, 6, 24, 120] """ 

The last two lines are an example of the use of the function and can be performed using the doctest module. Thus, you achieve this:

• You put an example of using the function, so your users will know how to use it;
• if you include a test in your test suite and often run tests, you will notice that if this example is violated by a code change
• writing such examples does not take too much time.

I usually start by creating stub functions and writing doctrines to get an idea of ​​how each function will work and what are the expected inputs / outputs; thanks to this approach, I always have at least a brief documentation of each function and module that I write.

From time to time I write a longer document explaining how my modules can be used (for my colleagues), and I always use the doctest syntax; however, when I solve your question, I never do more than this, sometimes I can write a blog comment about my work or in the library that I wrote, but I don’t have time to write longer documentation.

Answer 2

I write the structure of the documentation before the start and change it at the time of writing. I use Design by Contract as a structure, what to write in the documentation:

 http://en.wikipedia.org/wiki/Design_by_contract 

• Valid and invalid input values ​​or types and their values
• Return Values ​​or Types and Their Values
• Values ​​or types of errors and exceptions that may occur and their meanings
• Side effects
• Prerequisites whose subclasses can weaken (but not strengthen).
• Postconditions that can strengthen (but not weaken) subclasses
• Invariants that can strengthen (but not weaken) subclasses
• (less often). Performance guarantees, for example. to use time or space

Answer 3

• Make the code as self-documenting as possible -
• Draw drawings simply and easily electronically.
• Capture documents as sound bites rather than essays - for example, use an internal blog / wiki, etc. to capture information with screenshots and thoughts. Hint cards help

It helps me document when I go.

essentially simple tools for collecting ideas, and then they are easy to embed in large documents, if necessary. Use good tools. I use livewriter, mediwiki, snagit, onenote and freemind.

I hate writing documents - so I collect thoughts when I go.

Answer 4

These things should preferably be in the design specification (depending on the problem area). The rest I like to write in code with certain tags, and then automatically create documentation. One great tool for this is doxygen , but there are many others.

This way, the documentation is done almost automatically, as I like to comment on the code while working on it.

Answer 5

Well-written, well-commented code should not really need additional programmer documentation. As for end-user documents, I write help files for my applications at the same time as I implement each function, and tutorials when I did most of the coding. However, I came to the conclusion that writing textbooks earlier in the process would be a better idea.

Answer 6

I don't know, but you can use the XML comment syntax to help it a little. This will allow you to at least document your classes, properties, and method calls. Then you can use build automation to create the CHM file for you. Explore Sandcastle for this.

Otherwise, it’s useful to use a wiki that helps you track your team’s collaboration. Quite often, these things turn into "information pools" where people describe something about the system. They can also be used to create documentation.

Finally, release notes can be built if you have integration with your tracking repository. For example, TFS allows you to get all the work items and changes for any build, which is very useful for creating release notes.

Answer 7

It depends on the context of the documentation. If you document this for other developers, I suggest decent unit tests and variable names with comments, then the code will document it itself.

In the context of external APIs for use by clients, I usually take an approach to documenting an element when I finished writing this functionality.