Generating Comments with Tabnine

We maintain a compact image-optimizer demo that illustrates a full-stack flow and how to safely use AI-assisted code completion (like Tabnine) to generate inline documentation. Overview

Backend: a Python Flask service that accepts an uploaded image, processes it with OpenCV, and returns an optimized image.
Frontend: a React UI that uploads images, sets a quality parameter, and displays original vs optimized images with size comparisons.
Purpose: show practical, safe patterns for generating docstrings and inline comments with Tabnine and similar tooling, and how to avoid common pitfalls when documenting large functions.

Why use Tabnine (or similar)?

Speeds up writing docstrings, JSDoc, and inline comments.
Helps standardize documentation style.
Best used on small, focused selections (single functions or utility blocks) rather than whole files.

Below is a representative snippet from the Flask backend showing imports and the start of the upload endpoint. Note the correct standard-import name imghdr and robust early request checks:

# python
import logging
from flask import Blueprint, request, jsonify, send_file
import cv2
import numpy as np
import io
import imghdr
from werkzeug.utils import secure_filename
from PIL import Image

# Set up logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

bp = Blueprint('main', __name__)

@bp.route('/upload', methods=['POST'])
def upload():
    """
    Handle image uploads, validate input, process the image using OpenCV,
    and return the optimized image as binary data.
    """
    try:
        if 'image' not in request.files:
            logger.error('No image part in the request')
            return jsonify({'error': 'No image part in the request'}), 400

        image = request.files['image']
        if image.filename == '':
            logger.error('No image selected for uploading')
            return jsonify({'error': 'No image selected for uploading'}), 400

        # (Further processing steps omitted here for brevity)
    except Exception as e:
        logger.exception('An unexpected error occurred: %s', e)
        return jsonify({'error': 'An unexpected error occurred. Please try again later.'}), 500

Screenshot of a desktop browser showing an image-optimizer demo with "Original Image" and "Optimized Image" versions of a book cover titled "Coding with AI" and their file sizes. A gradient page background is shown inside the browser while a code editor and project files are visible behind the window.

Best practice note for large functions and AI tools

AI completion tools are most effective when you provide focused context. For long files or functions (80+ lines), generate documentation for a small selection (for example, one function or a helper). Then manually review and paste the docstring or comments into your code to avoid unintended edits to imports, logging, or scaffolding.

Common problem patterns and how to avoid them

Tools can produce broad diffs that remove critical imports, logging setup, or configuration.
Very large functions reduce the assistant’s ability to reason about context, leading to incorrect or incomplete suggestions.
Refactor large functions into logically smaller units (validation, decoding, processing, response). Smaller functions are easier to document and test.

Problem / Symptom / Recommended Fix

Problem	Symptom	Recommended Fix
Generated change removes imports or logging	Module breaks at runtime	Review diffs carefully; accept only targeted docstrings/comments
Tool produces incorrect refactors for large functions	Tests or runtime behavior change unexpectedly	Refactor into smaller functions before applying automated suggestions
Invalid parameter handling suggested	Server returns 4xx/5xx	Validate inputs explicitly and test edge cases locally

Example: safe generated docstring for the Flask upload endpoint

Rather than accepting a large automatic edit, generate a concise docstring for the function and apply it manually:

# python
def upload():
    """
    Handle the image upload request.

    This function:
    - Validates that an image file was provided in the request.
    - Validates file name and content type.
    - Retrieves the `quality` parameter from the request form (0-100).
    - Decodes the uploaded image into an OpenCV image and processes it
      according to the requested quality using `cv2.imencode`.
    - Verifies the processed image via Pillow to ensure it's valid.
    - Returns the processed image binary via `send_file` on success,
      otherwise returns a JSON error and appropriate HTTP status code.

    Returns:
        A Flask response: `send_file` with image binary on success,
        or `jsonify` with an error message and HTTP status on failure.
    """
    # (Function body continues...)

A corrected, concrete fragment for image processing

This is an example fragment you can use inside the upload endpoint after you validate the request and the image file:

# python
quality_raw = request.form.get('quality')
try:
    quality = int(quality_raw)
except (TypeError, ValueError):
    logger.error('Invalid quality value: %s', quality_raw)
    return jsonify({'error': 'Quality must be an integer between 0 and 100'}), 400

# Validate the quality parameter
if quality < 0 or quality > 100:
    logger.error('Invalid quality value: %s', quality)
    return jsonify({'error': 'Quality must be an integer between 0 and 100'}), 400

# Read the image bytes from the request
img_bytes = image.read()
img_array = np.frombuffer(img_bytes, np.uint8)
img = cv2.imdecode(img_array, cv2.IMREAD_UNCHANGED)

if img is None:
    logger.error('Failed to decode image: %s', image.filename)
    return jsonify({'error': 'Failed to decode image'}), 400

# Process the image with OpenCV
success, buffer = cv2.imencode('.jpg', img, [int(cv2.IMWRITE_JPEG_QUALITY), quality])
if not success:
    logger.error('cv2.imencode failed for image: %s', image.filename)
    return jsonify({'error': 'Failed to encode image'}), 500

# Create a BytesIO object from the encoded buffer (convert ndarray to bytes)
img_io = io.BytesIO(buffer.tobytes())

# Validate the processed image with Pillow
try:
    img_io.seek(0)
    processed_img = Image.open(img_io)
    processed_img.verify()
except (OSError, SyntaxError) as e:
    logger.error('Failed to process image: %s', e)
    return jsonify({'error': 'Failed to process image'}), 400

# Reset the BytesIO object pointer to the beginning
img_io.seek(0)

# Return the processed image as binary data
return send_file(img_io, mimetype='image/jpeg')

Practical workflow when using Tabnine (or other assistants) on large files

Select only the smaller code region you want documented (a single function or helper).
Ask Tabnine to “Document” or “Explain” that selection.
Review the generated docstring/comments. Copy only the docstrings/comments you want and paste them manually into the file — this prevents removal of imports and scaffolding.
Run tests or a manual smoke test after accepting any generated change.
Prefer refactoring large functions into smaller units before relying on automated documentation.

React frontend: JSDoc examples

Rather than rewriting an entire React file, generate short JSDoc comments for components or utilities and insert them manually.

// javascript
/**
 * Main application component for image optimization.
 * Handles image selection, quality adjustment, and optimization process.
 * Displays both original and optimized images with size comparisons.
 *
 * @returns {JSX.Element} The rendered application component.
 */
function App() {
  // React state hooks...
}

// javascript
/**
 * Formats a file size (in bytes) to a human-readable string.
 *
 * @param {number} bytes - Size in bytes.
 * @returns {string} Human-readable size (e.g., "1.23 MB").
 */
const formatFileSize = (bytes) => {
  if (bytes === 0) return '0 Bytes';
  const k = 1024;
  const sizes = ['Bytes', 'KB', 'MB', 'GB'];
  const i = Math.floor(Math.log(bytes) / Math.log(k));
  return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + ' ' + sizes[i];
};

Important warning

Never accept a generated change that removes imports, logging setup, or other scaffolding without a careful review. Those deletions will usually break your application.

Summary and final tips

Tabnine and similar tools can accelerate documentation work, especially for small, well-defined code blocks.
For functions longer than ~80 lines, prefer:
- Breaking the function into smaller units (validation, decoding, processing, response).
- Generating docstrings for selected regions instead of entire files.
- Manually pasting and reviewing generated docstrings/comments.
Always run tests (or a quick manual smoke test) after applying generated changes.

References and further reading

Course Introduction

Introduction to AI-Assisted Development

Planning Phase

Development Phase - Backend

Development Phase - Frontend

Project Completion

Generating Comments with Tabnine

Watch Video