When documenting a method, where should the comment normally go: immediately before the method declaration, or inside the method body near the opening brace? For example, should the explanation appear above `int func1() {}` or inside `int func2() {}`? I tend to prefer putting it inside because it visually feels like part of the method definition, but I often see API documentation written above the signature. Is placing comments before the method mainly a convention for documentation, while comments inside the body are intended for implementation details?
3 Answers
Put the comment before the method when you’re describing what the method does, its parameters, return value, or other information useful to someone calling it. A comment inside the method should usually explain a particular line or implementation detail, not document the method as a whole.
The exact style varies by language and community, but the general convention is consistent: place public API documentation before the method signature, and reserve comments inside the body for local implementation details. The important thing is to follow the conventions of the project and use comments where they add information rather than merely restating the code.
For C or C++, tools such as Doxygen use a standard comment format placed before the method declaration. IDEs can also recognize those comments and display them as documentation when you call or inspect the method. Following the language or project’s established style guide is usually the best choice.
That makes sense. Using the documented format also lets the comments become searchable API documentation instead of just being notes in the source.
A useful distinction is: comments before the method explain what the method does, while comments inside it explain why a specific piece of code is unusual or necessary.