# 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
@JosephWright I guess I'm implicitly leaning more towards package/class code, simply because that type of code tends to be more complex and hence have greater need for good commenting. But I'd quite like answers to tackle both document code and package code. –  John Wickerson May 24 '13 at 6:50
@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 -- 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
At least one of the questions (about sectioning devices) only really applies to document code. Since the default (and good) answer for package code seems to be "use a .dtx file," it seems to me that refocusing the question on document code may be helpful. –  Charles Staats May 27 '13 at 15:25