Best practice for writing comments in LaTeX documents

Question

I would like to find out about recommended practices when using comments in LaTeX documents.

Some programming languages are quite clear about how to use comments in source code: for instance, [here] are some guidelines about using comments in OCaml, and [here] are some guidelines for Java. But what about LaTeX?

Here are a few questions that answerers might like to address:

• Should I put comments above/below/within each command I define?
• Should comments come at the end of an existing line, or on a line by themselves?
• Is there an accepted way of using comments to define each parameter of a command?
• What about using lines of comment symbols as a sectioning device?
• What sort of comments should one put at the head of a file?

Below is some (abridged) code of mine that makes liberal use of comments. I thought it might be useful as a starting point.

\documentclass{article}

% ===================================================================
% TODO LIST
%
% * make "draw grid" key work properly
%
% * make a macro for partially-rounded rectangle

\usepackage{tikz}
\usetikzlibrary{showgrid}
\usetikzlibrary{calc}
\usepackage{etextools}

\makeatletter

% ===================================================================
% GENERAL-PURPOSE COMMANDS

% Extension of the ExpandNextTwo command provided by etextools
\def\ExpandNextThree#1#2#3#4{%
  \ExpandNext{\ExpandNext{\ExpandNext{#1}{#2}}{#3}}{#4}}

% ===================================================================
% CONSTANTS

\newcommand\jusColor{black!50} % bg colour of "justification" steps
\newcommand\comColor{black}    % bg colour of "command" steps 

% ===================================================================
% MINOR COMMANDS

% The expression
%   \@defineShape{foo}{34}{57}
% expands to the following definitions
%   \xdef\shapes@foo@left{34}
%   \xdef\shapes@foo@right{57}
\newcommand*\@defineShape[3]{%
  \expandafter\xdef\csname shapes@#1@left\endcsname{#2}
  \expandafter\xdef\csname shapes@#1@right\endcsname{#3}
}

\newenvironment{mydiagram}[1][]{%
  %
  % Process keys
  \pgfkeys{/mydiagram/.cd,scale=1,start shapes={},#1}
  %
  % Nudge vertical cursor up a bit. This is a hack to 
  % counteract the fact that the first row does not have
  % any steps in it. Without this hack, the labels in 
  % the first row would be printed too far down.
  \setcounter{VCursor}{-\defaultStepHeight}
  %
  % Make the \\ command a synonym for \finishrow. The
  % reason for this is mainly to exploit the syntax
  % highlighting in AucTeX, which emphasises \\ commands.
  \renewcommand\\{\finishrow}

Answer 1

Donald E. Knuth not only gave us TeX, he can also be considered the father of literate programming. The principle of literate programming is also applied when preparing a package for LaTeX.

A .dtx file contains an explanation of the macros in plain English comments whilst being interspersed with snippets of the real macros in LaTeX code. From this .dtx file, both the package code and the documentation PDF are generated.

In order to get started with .dtx files, I can recommend using the CTAN support package dtxgen by the hand of Wybo Dekker.