# Best practice for writing comments in LaTeX documents

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?

• 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}

-
Are you thinking documents or package/class code? Are you planning to use the code 'directly' or extract it from the commented material? –  Joseph Wright May 24 '13 at 6:37
The order things appear should generally be reading order: that might be either before or after the Tex code. Generally, I follow Pike's C conventions, which is introduce concepts before code, explain tricky bits after, and don't bury your code in comments. I think @JosephWright means .dtx or similar for extraction. –  Charles Stewart May 24 '13 at 7:18
@JohnWickerson As Charles says, if you are creating package code I wonder if you want to put the comments directly in a .sty file or use for example a .dtx to allow typesetting of documentation/comments and extraction of the uncommented code. –  Joseph Wright May 24 '13 at 7:32
@JohnWickerson -- a good, if overwhelming, example of a .dtx file is source2e. run texdoc source2e to see the output. –  barbara beeton May 24 '13 at 14:19
@JohnWickerson -- on the user side, never put a comment in anything that goes inside of \index{...}. you won't get warned, but when the .ind file is read back in, the job will crash. –  barbara beeton May 24 '13 at 14:21