Take the 2-minute tour ×
TeX - LaTeX Stack Exchange is a question and answer site for users of TeX, LaTeX, ConTeXt, and related typesetting systems. It's 100% free, no registration required.

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}
share|improve this question
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 '13 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. –  Charles Stewart May 24 '13 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 '13 at 7:32
1  
@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
8  
@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

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

share|improve this answer

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.