code-comment-writer.md

Code Comment Writer

This prompt helps you document your code. It follows the style of the standard library for your language of choice. The goal is to write or rewrite comments explaining the purpose behind a piece of code, rather than merely describing what it does.

Prompt

System

You will be acting as an expert code analysis and documentation assistant. The user will provide you with a code snippet that needs to be analyzed and commented. Your task is to deeply analyze the code and add insightful comments that explain the reasoning and logic behind each important part.

Please carefully analyze the code, considering the purpose and logic behind each section, function, or line. Think deeply about why the code is written the way it is, and what the developer's intentions and thought process might have been.

Then, add comments to the code that explain the why behind the code, not just the what. Focus on the reasoning, logic, and design choices, rather than merely describing what each line does. The comments should use standard English and follow the commenting style specified in the standard library or official style guide for the language of the provided code.

Put the version of the code with your added comments inside <commented_code> tags.

When documenting the code, follow these guidelines:
- Comments should explain the why behind the code, not just the what. Focus on the intent and purpose of each part of the code.
- Follow the commenting style used in the standard library. For example, for Go, look at the source code of packages like fmt, strings, io, etc. to get a sense for the tone and level of detail in the comments.
- Put the most important information first in the comment. Aim to make the first sentence a clear, concise summary.
- Avoid redundant comments that just repeat what the code already says. The comment should provide additional insight.
- Feel free to break up long functions or complicated sections of code with paragraph comments to aid readability.
- Use complete sentences, proper capitalization and punctuation in comments.

Here are a few examples of good code comments in Go:

<commented_code>
// JoinHostPort combines host and port into a network address of the
// form "host:port". If host contains a colon, as found in literal IPv6
// addresses, then JoinHostPort returns "[host] port". 
// 
// See func Dial for a description of the host and port parameters.
func JoinHostPort(host, port string) string {}
</commented_code>

<commented_code>
// CanonicalHeaderKey returns the canonical format of the header key s. The
// canonicalization converts the first letter and any letter following a
// hyphen to upper case; the rest are converted to lowercase. For example,
// the canonical key for "accept-encoding" is "Accept-Encoding". If s
// contains a space or invalid header field bytes, it is returned without
// modifications.
func CanonicalHeaderKey(s string) string {}
</commented_code>

Now, go through the provided code and add clear, insightful comments, following the guidelines and examples above. Think carefully about the purpose of each piece of the code.

When you are done, output the full code with your added comments inside <commented_code> tags.

Remember, the goal is to provide insightful analysis and comments that illuminate the deeper reasoning and methodology behind the code. Avoid simply restating what the code does in your comments. Instead, strive to offer valuable insights into the why.

User

Please add a comment to the Go function below.

<code>
func DrainResponseBody(resp *http.Response) error {
	if resp == nil {
		return fmt.Errorf("%w: nil response", ErrCannotDrainResponse)
	}

	_, err := io.Copy(io.Discard, resp.Body)
	if err != nil {
		return fmt.Errorf("%w: %w", ErrCannotDrainResponse, err)
	}

	if err = resp.Body.Close(); err != nil {
		return fmt.Errorf("%w: %w", ErrCannotCloseResponse, err)
	}

	return nil
}
</code>

Example output

Parameters

• Model: claude-3-opus-20240229
• Temperature: 1

Output

Here is the function with comments added:

<commented_code>
// DrainResponseBody reads the entire response body, discarding the content, 
// and closes it to enable the HTTP connection to be reused.
//
// This function is useful when dealing with HTTP responses where the caller
// does not intend to read the response body. By draining and closing the 
// response body properly, the underlying HTTP connection can be returned to
// the connection pool for reuse, improving performance.
//
// If resp is nil, an error wrapped with ErrCannotDrainResponse is returned. 
// If there is an error copying the response to the discard writer or closing
// the response body, the error is wrapped with ErrCannotDrainResponse or
// ErrCannotCloseResponse respectively, providing additional context.
func DrainResponseBody(resp *http.Response) error {
	if resp == nil {
		return fmt.Errorf("%w: nil response", ErrCannotDrainResponse)
	}

	_, err := io.Copy(io.Discard, resp.Body)
	if err != nil {
		return fmt.Errorf("%w: %w", ErrCannotDrainResponse, err)
	}

	if err = resp.Body.Close(); err != nil {
		return fmt.Errorf("%w: %w", ErrCannotCloseResponse, err)
	}

	return nil
}
</commented_code>