# Class Design: Environment vs. Macro

I have seen What are the consideration when choosing either newcommand or newenvironment? but I think this is a little more specific. If it's a duplicate, then so be it. If the second part of the question is too speculative, then I can edit it out.

Let's say I were making an exam class (I know there are many, but just for example).

\documentclass{myexam}
% preamble
\begin{document}
% content
\end{document}


Clearly, if would be nice for such a class to provide a \question command of some sort. Two approaches would be:

(1) Provide a \question macro.

\documentclass{myexam}
% preamble
\begin{document}
\question Here is my question.
\end{document}


(2) Provide a \begin{questions} environment (list).

\documentclass{myexam}
% preamble
\begin{document}
\begin{questions}
\question Here is my question.
\end{questions}
\end{document}


I have two related questions:

1. If \begin{questions} were hidden in something like \AtBeginDocument, then to the user, the approaches are (mostly) identical. In such a case, does either approach offer any specific advantage/disadvantage?
2. Is one approach semantically superior? For example, would a competent user expect one or the other?

One possible disadvantage of the environment/list approach would be that to add a non-question, the environment/list may need to be explicitly stopped and restarted.

-
In most cases, commands are for short input, environments for longer. But that's a matter of code reading and common habbits, rather than semantics. Also, there are some subtle differences between what is acceptable in a command or in an environment body (see for example the documentation of the verbatim package). –  T. Verron Mar 13 '13 at 9:34
Separate comment because separate point: the syntax \question <Content here> would definitely be unusual. Out of a specific environment (itemize, etc for \item or questions for question) command arguments should always be delimited by braces or square brackets. And even in these environments, this ambiguity of the language is a valid point raised regularly by latex competitors. –  T. Verron Mar 13 '13 at 9:37
Well, the exam class uses approach (2), i.e. the list like one. For my exsheets package I decided to use an environment for each question to be able so suppress them on a per question basis... –  clemens Mar 13 '13 at 9:44

I don't think there is any point in defining a new environment and then hiding it inside the \begin{document} code, you may as well just expose the content of the environment at the top level if you don't want the user to use the environment explicitly.

Before I got to the end of your question I was thinking the exact opposite of this

One possible disadvantage of the environment/list approach would be that to add a non-question, the environment/list may need to be explicitly stopped and restarted.

It seems to me that the main advantage of the environment is exactly that: It provides a way of marking things that are non-questions.

If you go

\question  what's your name

Note for users of American English: I'm British.


Then it isn't clear whether the note is part of the second question or following the list of questions.

However that is resolved if you go

\begin{questions}

\end{questions}

Note for users of American English: I'm British.


or

\begin{questions}

Note for users of American English: I'm British.

\end{questions}


Telling where things end is related to the other macro syntax choice that you don't mention in your question but is discussed in the answers and comments on the linked questions. Using a macro with arguments makes it very clear where the argument ends but may have other disadvantages depending on the expected length and nature of the content of the questions.

\question {what's your name}


Thanks for the feedback. After thinking a bit more, I tend to agree with your point about delineating questions from non-questions. I suggested hiding \start{questions} as a thought device to remove the user from the equation and to compare the two at a technical level, rather than a user level. Thanks again. –  Scott H. Mar 14 '13 at 0:25