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.


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



% ===================================================================

% Extension of the ExpandNextTwo command provided by etextools

% ===================================================================

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

% ===================================================================

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

  % 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.
  % Make the \\ command a synonym for \finishrow. The
  % reason for this is mainly to exploit the syntax
  % highlighting in AucTeX, which emphasises \\ commands.
  • 5
    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, 2013 at 6:37
  • 2
    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. May 24, 2013 at 7:18
  • 2
    @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, 2013 at 7:32
  • 1
    @JohnWickerson -- a good, if overwhelming, example of a .dtx file is source2e. run texdoc source2e to see the output. May 24, 2013 at 14:19
  • 9
    @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. May 24, 2013 at 14:21

1 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.

enter image description here

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .