How do you comment in API?

Commenting in API (Application Programming Interface) code is an important part of good software development practices. Clear, concise comments make code easier to understand and maintain for other developers or your future self. There are a few key things to keep in mind when writing effective code comments in API:

Use Consistent Commenting Conventions

Most programming languages and API documentation have standard conventions for writing different types of comments. Following consistent conventions makes code immediately more readable to other developers familiar with those standards. Some examples include:

• Block comments that span multiple lines, often marked with /* at the start and */ to end.
• Single line comments with // preceding the comment.
• Docstrings and other syntax for commenting functions, classes, and methods.
• Specific tags like TODO, NOTE, WARNING to call out important information.
• Javadoc and other formatted syntax for generating API documentation from comments.

Adhering to common commenting conventions results in professional, maintainable API code.

Explain Intent and Reasoning

Effective comments don’t just reiterate what the code is doing – they explain the intention and reasoning behind the code. Some examples of insightful comments:

• Why a certain approach was chosen
• Assumptions made in the implementation
• Important details another developer would need to know
• Restrictions or rules that are not immediately clear
• Sources for logic used such as research papers or mathematical techniques

Comments that explain the “why” behind code help prevent misunderstandings and mistakes when others modify or update the code in the future.

Highlight Important Details

Comments should explicitly call out important information developers need to be aware of. For example:

• Known bugs or quirks in a piece of code
• Areas of code that still need improvement
• Parts of the code that are complex or confusing
• Details related to security, performance, scaling
• Business logic that impacts how the code functions

Flagging noteworthy details saves time and prevents problems down the road.

Avoid Obvious or Redundant Comments

Don’t over-comment! Code should be self-documenting whenever possible. Avoid comments that restate what the code already clearly does. For example:

• Obvious variable names like // set counter to 0
• Restating the method name // getUser method gets the user
• Overexplained logic // initialize array to empty

Too many redundant comments clutter up code and make it harder to read. Keep comments high-value by not pointing out the obvious.

Make Comments Consistent and Current

Comments need regular maintenance like any other code. As code evolves over time:

• Update existing comments to match current logic
• Remove comments on old, unused code sections
• Add new comments on recent additions

Outdated comments can cause confusion and waste time. Keep them current.

Best Practices for Readable Comments

For maximum readability, follow these best practices in writing comments:

• Be concise yet descriptive
• Use complete sentences with proper punctuation and capitalization
• Break long comments into short paragraphs on separate lines
• Include links to external references where applicable
• Avoid using special characters or formatting in comments

Readable commenting style improves understanding and maintainability.

Tools for Documenting Code

The right tools can make commenting more efficient and integrate documentation into your development workflow. Some examples:

Look for documentation generators compatible with your platform and coding language for more robust docs.

Commenting Best Practices by Language

While core principles are universal, commenting syntax varies somewhat by language:

Java

• Use Javadoc commenting style for documenting classes, methods, etc.
• Adhere to Java coding standards for single line and block comments
• Leverage tags like @param, @return for method parameters and return values
• Generate HTML docs and reference from Javadocs

Python

• Use docstrings for modules, classes, methods following PEP 257
• Utilize “””triple quotes””” for multiline block comments
• Add # hashes before line comments
• Use Sphinx, reStructuredText, and Read the Docs for documentation

C#

• Follow .NET Framework guidelines including using /// for XML docs
• Make comments consistent with language keywords like //TODO:
• Take advantage of feature summary tags ///
  
• Generate documentation with tools like DocFX and Sandcastle

JavaScript

• Use // for single line comments
• For blocks, wrap comments in /* */ markers
• Begin files with block comments describing contents
• Use JSDoc style tags to annotate classes, methods, etc.
• Include typedoc JSON definitions

Check language best practices to ensure great commenting style.

Team Commenting Standards

For a team of developers, establish shared commenting conventions up front for consistency across a codebase. Key elements to standardize:

• Comment syntax, markers, and placement
• Tagging important information like TODOs
• Expectations for comment density and locations
• Integrating documentation generation
• Commenting mobile, web, backend, and other domains
• When to remove or update comments

Defined standards for commenting keep a collaborative project coherent over time.

Code Review for Commenting

Incorporate commenting practices into code review and QA processes. Look for:

• Adherence to project commenting guidelines
• Clear, meaningful explanations of intent and reasoning
• Highlighted special cases, limitations, dependencies
• Documentation consistent with changes
• Whether comments need updating
• Readability – formatting, spelling, language

Reviewing code comments ensures quality documentation for the team.

Templating Commenting Structure

Using templates or boilerplate commenting structures improves consistency and saves time. For example:

• Template for file headers describing contents
• Standard formats for documenting classes, variables, methods
• Common tags like TODO, WARNING, DEPRECATED
• General templates for inline single line comments

Code generators and IDE plugins can also auto-insert comment templates.

Commenting for Maintainability

Comments are critical for maintainability – allowing anyone to pick up and understand code months or years later. Key maintainability aspects:

• Overview of architecture, frameworks, patterns
• Summaries of complex logic or algorithms
• Deprecated sections clearly marked
• References to external resources
• No outdated or conflicting comments

Great comments allow new team members to quickly comprehend legacy projects.

Balancing Over and Under Commenting

Strive for the right amount of commenting – too much can be disruptive, too little leaves gaps in understanding. Ideal balance:

• Comments focus on “why”, not restating “what”
• Enough context to understand intent and purpose
• Highlight quirks and specifics needed by other developers
• Don’t force readers to parse excessive commenting
• Leverage documentation generation to avoid duplication

Clear, concise comments augmented by good docs hit the commenting sweet spot.

Evaluating Commenting Quality

How do you know if API code comments are well written? Look for:

• Adherence to language/platform commenting conventions
• Explanation of intent, approach, constraints
• Callouts of key details and caveats
• Documentation integrated and in sync
• Formatting for quick scanning
• Conciseness and relevance
• Consistency across codebase

Great comments tick all the boxes for understandability and maintenance.

Conclusion

Commenting is an essential practice for clean, maintainable API code. By adhering to language conventions, explaining reasoning, highlighting issues, keeping comments current, and balancing quantity, developers can produce professional API documentation alongside logic. With some forethought and consistency, comments can make all the difference in producing readable, reusable, and sustainable APIs.