.. include:: /include/custom_roles.txt
.. sectnum::
.. _code_documentation:

.. figure:: /_static/images/title1.png
    :alt: Source-Code Documentation Best Practices
    :align: center

    ..

    By Victor Wheeler

|



****************************************
Source-Code Documentation Best Practices
****************************************

If you are a career software developer like I am, you are probably saying, "Here we
are again talking about the age-old (sometimes controversial) topic of documenting
source code."  Yet it is my hope that you will find this article unique and important
in the industry because of the understandings it brings to tech writers, programmers,
and executives who oversee software development teams (and are tempted to tell them
not to spend time documenting source code).

This author's aim is to address this particular audience and help bring about
agreements that facilitate team coordination and cooperation as regarding documenting
source code.  My aim is to teach development teams faced with creating (and/or
maintaining) source code that has a long life, especially when there will be many
releases over its lifetime, and especially in collaborative development environments,
that proper source-code documentation plays a huge role in the success of that
software or library because if how it enhances that source code's:

- :term:`understandability`,
- :term:`maintainability`,
- :term:`extendibility`,
- :term:`correctness` (see :ref:`ddd articles`),
- :term:`reliability`,
- :term:`ease of use`,
- :term:`timeliness`,
- :term:`repairability`, and
- :term:`economy`

throughout its lifetime.

To be clear:  this *does not apply* to one-off programs that are written once,
released, and never modified again, or that will have a very short maintenance
period.  It applies to programs and libraries that will be seen, and may be enhanced,
modified and/or fixed over a long period---the longer the period, the more it applies.
It applies doubly when more than one person is involved in its development.


.. toctree::
    :maxdepth: 3
    :caption: Contents:
    :numbered:

    introduction
    documentation
    software_documentation
    source-code_documentation
    knuth_on_literate_programming
    oosc2_on_terseness
    glossary
    bibliography