Where Should Comments Go When Documenting a Method?
Asked by
MellowCedar47
When documenting a method definition, should the comment appear before the method signature or inside the method body? For example, should I write a comment immediately above the declaration, or place it as the first line inside the implementation? I tend to prefer the second style because it feels associated with the method's code, but API documentation often places comments before the signature. Is putting the comment before the method a convention specifically intended for documentation?
Answers
The exact syntax varies by language, but most languages and style guides follow the same general idea: put public documentation immediately before the declaration. Use an inner comment only when it clarifies a specific step in the implementation.
Reply to this answer
Put the comment before the method when you’re explaining what the method does, its inputs, outputs, or other API behavior. A comment inside the method should usually explain a particular implementation detail or why the following code is unusual—not document the method as a whole.
Reply to this answer
For C or C++, tools such as Doxygen use comments placed before the method declaration or definition to generate API documentation. Many IDEs also recognize that format and display it when you use the method elsewhere, so the preceding-comment style is the usual choice for method documentation.
MellowCedar47: That makes sense—the documentation comment belongs to the method declaration, while comments inside the body are for implementation details.
Reply to this answer
Add your answer
Answers are reviewed before publication.
PixelNook31: A useful distinction is: document the method before its signature, and explain a surprising line or block inside the body.